Sending JSON to REST API Endpoint

What is JSON?

JavaScript Object Notation is a data interchange format that specifies formatting rules for the portable representation of structured data. JSON represents four primitive types (strings, numbers, booleans, and null) and two structured types (objects and arrays).

What is HTTP POST?

HTTP POST is one of the nine standard HTTP methods. The POST method requests that the REST API server accept the object enclosed in the body of the message at the endpoint identified by the Request-URI. The POST method differs from HTTP HEAD and GET requests in that HTTP POST requests can change the server's state.

What is REST API?

REST stands for Representative State Transfer and is a way of connecting two computer systems over the Internet. The REST API is a browser and programming language agnostic. You can run your REST API client in any modern browser or create a desktop or mobile REST API application using any programming language.

The REST API defines a set of rules for developers to create APIs:

1. Client-server: the REST API client user interface (website, desktop or mobile application) should be decoupled from the REST API server (request processor and data storage) so that each part can be developed and scaled individually.
2. Stateless: Every REST API request must be executed with all the necessary data, without assuming that the server might have any data from previous REST API client requests.
3. Layered: the REST API client does not need to know if it communicates with an actual server or an intermediary. Intermediate servers (proxies or load balancers) can provide the underlying REST API server with additional scalability and security.
4. Cacheable: each REST API response must be defined as cacheable or not.

REST API POST Example

To send data to the REST API server, you must make an HTTP POST request and include the POST data in the request's body. You also need to provide the Content-Type: application/json and Content-Length request headers. Below is an example of a REST API POST request to a ReqBin API endpoint.

POST /echo/post/json HTTP/1.1
Host: reqbin.com
Accept: application/json
Content-Type: application/json
Content-Length: 81

{
  "Id": 78912,
  "Customer": "Jason Sweet",
  "Quantity": 1,
  "Price": 18.00
}

In this REST API POST request example, the server informs the REST API client that it has returned JSON by sending Content-Type: application/json header in response.

Server response to our test REST API POST request.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 19

{"success":"true"}

What is the correct content type when posting JSON to a REST API endpoint?

The official MIME type for JSON is application/json. To POST JSON data to the server, you must specify the data type in the body of the POST message using the appropriate Content-Type request header.

Content-Type: application/json

Why is it important to specify the correct Content-Type when posting JSON to a REST API endpoint?

If you don't pass the correct Content-Type header to the server, your application may not work. The REST API server needs a valid Content-Type header to interpret the request message body data correctly. This is especially important for MVC frameworks that implicitly convert values from JSON to local variables.

If your REST API client expects JSON data from the server, it must also send the Accept: application/json request header. The Accept header tells the server that the client can accept and process JSON data. If the server returns data in JSON format, it must inform the API client of the data type using the Content-Type: application/json response header.

Accept: application/json

See also

• SOAP vs REST
• How do I get JSON from a REST API endpoint?
• Test JSON Response Online
• JSON Payload Example