API Format: The Data Formats APIs Use for Requests and Responses

API format is the way data is arranged in a request and a response. For web APIs today the default is JSON.

An API, or application programming interface, is a contract between two programs. The format is the part of that contract that says how the data looks on the wire. Both sides must agree, or the receiver cannot read the message.

If a question asks which format web APIs commonly use to return data, the answer is JSON. XML is the older alternative and is still common in enterprise and SOAP services.

The format is announced in a header. The sender sets Content-Type to say what it sent. The caller sets Accept to say what it wants back.

The common API data formats

JSON wins because it is short, readable by a person, and parsed natively by JavaScript. XML carries more structure, such as namespaces and schemas, at the cost of size.

The shape of a request and a response

Format also covers the whole envelope, not only the body. A request has four parts.

• Method. GET, POST, PUT, PATCH or DELETE, which states the action.
• Path. The resource being addressed, such as /v1/users.
• Headers. Content type, accepted type, authentication and version.
• Body. The payload, which GET requests usually leave empty.

A JSON request looks like this.

POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "name": "Ana Silva",
  "email": "ana@example.com"
}

The response carries a status code, headers and its own body.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 1042,
  "name": "Ana Silva",
  "email": "ana@example.com"
}

The same record in XML is longer and uses nested tags.

<user>
  <id>1042</id>
  <name>Ana Silva</name>
  <email>ana@example.com</email>
</user>

The error format matters as much as the success format

Many APIs define a careful success body and then return raw text on failure. That forces every caller to guess.

Pick one error shape and use it everywhere. A useful one has a machine readable code, a human readable message, and an identifier for the failed request.

{
  "error": {
    "code": "invalid_email",
    "message": "The email address is not valid.",
    "requestId": "b71f2c9a"
  }
}

Match the HTTP status code to the body. A 400 means the caller sent something wrong. A 500 means the service failed.

How to choose a format

Most of the time you do not choose. You use JSON because your callers expect it.

• Public web API. Use JSON. It is the safest default for outside developers.
• Internal service to service traffic. Protocol Buffers over gRPC is smaller and faster.
• File upload. Use multipart/form-data, since JSON handles binary data poorly.
• Legacy or regulated systems. XML with a schema may be required by the other side.
• Bulk export. CSV is still the format most data teams can consume.

How to Prepare

• Know the difference between format and design. Format is JSON or XML. Design is the resource names, status codes and error bodies. Interviewers ask about both. Grokking the System Design Interview covers the design half.
• Learn the basics before the patterns. Grokking System Design Fundamentals explains clients, servers and protocols in order.
• Compare REST and GraphQL. They use the same JSON but ask for data differently. See what is GraphQL and how does it compare to REST.
• Be able to version an API. Read best practices for API versioning before you propose a URL scheme.
• Know where the gateway sits. What is an API gateway explains the piece that enforces format and auth.
• Do not confuse an API with an SDK. What is an SDK versus an API? clears up the most common mix up.