How do I post JSON to a REST API endpoint?

To post JSON to a REST API endpoint, you must send an HTTP POST request to the REST API server and provide JSON data in the body of the POST message. You also need to specify the data type in the body of the POST message using the Content-Type: application/json request header. In this REST API POST example, we also send the Accept: application/json request header to tell the REST API server that the API client expects JSON in response.
How do I post JSON to a REST API endpoint? Send
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
}
Updated: Viewed: 49153 times

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 REST API endpoint.

REST API POST Request
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.

REST API Server Response
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 for JSON
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 JSON header example
Accept: application/json

See also

Generate Code Snippets for REST API POST Example

Convert your REST API POST request to the PHP, JavaScript/AJAX, Curl/Bash, Python, Java, C#/.NET code snippets using the ReqBin code generator.