Question 1

Step 4: Design the Request Schema.

Accepted Answer

The server needs to know exactly what data constitutes a valid address. We define a JSON schema requiring specific fields: street (string, required), city (string, required), zipCode (string, exactly 5 characters, required), and isDefault (boolean, optional). If a client sends a request missing the city field, the API endpoint is designed to reject it immediately before even touching the database. Step 5: Design the Response Schema and Status Codes. If the creation is successful, the server should return an HTTP 201 Created status code. The response body should echo back the created address, but crucially, it must include the newly generated unique database identifier (e.g., {"id": "addr_456", "street": "123 Main St", ...}). Step 6: Define Error States. We must explicitly define what happens when things go wrong. If the zipCode is only 4 characters, the endpoint returns a 400 Bad Request. If the Authorization token is expired, it returns a 401 Unauthorized. By documenting every single one of these steps in an OpenAPI specification file, developers create a rigid, mathematically verifiable blueprint. A client application developer can look at this blueprint and know exactly how to format their HTTP request to successfully add an address without ever needing to speak to the backend engineer who built it.

Question 2

What is the difference between an API and an API endpoint?

Accepted Answer

An API (Application Programming Interface) is the complete set of rules, protocols, and tools that allow two software applications to communicate. It encompasses the entire system, including authentication, rate limiting, and backend logic. An API endpoint is a single, specific URL within that larger API that provides access to one specific resource or function. If the API is a massive library, an endpoint is the specific shelf where a particular book is located.

Question 3

Why do we use JSON instead of XML for API payloads?

Accepted Answer

JSON (JavaScript Object Notation) became the industry standard because it is significantly lighter, faster to parse, and easier for humans to read than XML. XML requires opening and closing tags for every piece of data (e.g., John), which drastically increases the file size and bandwidth required to transmit the payload. JSON uses a much simpler key-value syntax (e.g., "name": "John"), which maps natively to objects in modern programming languages like JavaScript, Python, and Ruby, eliminating the need for complex parsing libraries.

Question 4

How do I secure an API endpoint from unauthorized access?

Accepted Answer

Securing an endpoint requires implementing authentication to verify identity, and authorization to verify permissions. The industry standard is OAuth 2.0 combined with JSON Web Tokens (JWT). When a user logs in, the server issues a cryptographically signed JWT. The client must include this token in the Authorization header of every subsequent API request. The endpoint inspects the token's signature; if it is valid and not expired, the request proceeds. If the token is missing or forged, the endpoint instantly rejects the request with a 401 Unauthorized status code.

Question 5

What is the difference between PUT and PATCH methods?

Accepted Answer

Both PUT and PATCH are used to update existing resources, but they operate differently. PUT is heavily destructive; it replaces the entire resource with the payload provided. If a user record has 10 fields and you send a PUT request with only 2 fields, the server will overwrite the record, effectively deleting the other 8 fields. PATCH is used for partial updates. If you send a PATCH request with only 2 fields, the server will update only those specific fields and leave the remaining 8 untouched.

Question 6

Should I use path parameters or query parameters?

Accepted Answer

Path parameters are used to identify a specific, unique resource within a hierarchy, acting as a mandatory identifier. For example, in GET /users/123, "123" is a path parameter identifying the specific user. Query parameters are used to sort, filter, or paginate a collection of resources, acting as optional modifiers. For example, in GET /users?role=admin&limit=10, the query parameters filter the broad collection of users down to a specific subset. You should never use query parameters to identify a single, specific entity if a unique ID exists.

Question 7

What is an OpenAPI Specification (Swagger) file?

Accepted Answer

An OpenAPI Specification is a standardized, machine-readable text file (written in YAML or JSON) that comprehensively describes an entire API. It acts as the ultimate blueprint, documenting every single endpoint, the allowed HTTP methods, the required authentication, and the exact JSON schemas for all requests and responses. Because it is machine-readable, developers use this file to automatically generate interactive documentation portals, create automated testing scripts, and even auto-generate the boilerplate code for both the client and server applications.

Question 8

How do I handle breaking changes in my API design?

Accepted Answer

When you must make a change that will break existing client applications—such as deleting a required field, changing a data type from a string to an integer, or drastically altering the response schema—you must implement versioning. The most common approach is URI versioning, where you create a new endpoint path (e.g., moving from /v1/orders to /v2/orders). You must maintain the /v1/ endpoints for a specified deprecation period, allowing clients time to update their code to consume the /v2/ endpoints before you finally turn off the old version.

Question 9

What is Cross-Origin Resource Sharing (CORS) and why does it block my endpoints?

Accepted Answer

CORS is a security mechanism built into modern web browsers to prevent malicious websites from making unauthorized API requests on behalf of a user. If a frontend web application hosted on domain-a.com tries to make an API call to an endpoint hosted on domain-b.com, the browser will block the request by default. To allow this, the API endpoint must be configured to return specific HTTP headers (like Access-Control-Allow-Origin: https://domain-a.com), explicitly telling the browser that the requesting website is permitted to access the data.

API Endpoint Builder

Command Palette