Introduction

The JSON Placeholder API is a RESTful web service that shows how Spring REST docs works for a public API.

HTTP verbs

The Example API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, overwrites all fields

PATCH

Used for partial updates to an existing resource

DELETE

Used to delete an existing resource

HTTP status codes

The JSON Placeholder API uses a few status codes in the API.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

404 Not Found

The requested resource did not exist or the operation is not supported.

For more information on status codes, see the w3 standard

Errors

Whenever an error occurs, the body will contain an empty JSON object. For example:

$ curl 'http://jsonplaceholder.typicode.com/posts' -i -X DELETE -H 'Accept: */*'

or

DELETE /posts HTTP/1.1
Accept: */*
Host: jsonplaceholder.typicode.com

will respond with:

HTTP/1.1 404 Not Found
Date: Mon, 30 Jan 2017 14:39:45 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 3
Connection: keep-alive
Set-Cookie: __cfduid=de2e7130b214b132eec734991fc271c8b1485787184; expires=Tue, 30-Jan-18 14:39:44 GMT; path=/; domain=.typicode.com; HttpOnly
X-Powered-By: Express
Vary: Origin, Accept-Encoding
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
X-Content-Type-Options: nosniff
Etag: W/"2-mZFLkyvTelC5g8XnyQrpOw"
Via: 1.1 vegur
Server: cloudflare-nginx
CF-RAY: 3295acd133f13cdd-CPH

{ }

Resources

Posts

The posts resource returns posts for various inputs

List of Posts

A `GET` request with no parameters will return a list of all posts

Example request

$ curl 'http://jsonplaceholder.typicode.com/posts?userId=1' -i -H 'Accept: application/json' -H 'Content-Type: application/json; charset=UTF-8'

or

GET /posts?userId=1 HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=UTF-8
Host: jsonplaceholder.typicode.com

Example response

HTTP/1.1 200 OK
Date: Mon, 30 Jan 2017 14:39:43 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: __cfduid=dff52f9f893b37ee7a5c25e39f6ed60551485787183; expires=Tue, 30-Jan-18 14:39:43 GMT; path=/; domain=.typicode.com; HttpOnly
X-Powered-By: Express
Vary: Accept-Encoding
Access-Control-Allow-Credentials: true
Cache-Control: public, max-age=14400
Pragma: no-cache
Expires: Mon, 30 Jan 2017 18:39:43 GMT
X-Content-Type-Options: nosniff
Etag: W/"aa6-ntTwGoY/BKcKFax4FoJc3Q"
Content-Encoding: gzip
Via: 1.1 vegur
CF-Cache-Status: HIT
Server: cloudflare-nginx
CF-RAY: 3295acc9a14c3cef-CPH
Content-Length: 2646

[ {
  "userId" : 1,
  "id" : 1,
  "title" : "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body" : "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}, {
  "userId" : 1,
  "id" : 2,
  "title" : "qui est esse",
  "body" : "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
}, {
  "userId" : 1,
  "id" : 3,
  "title" : "ea molestias quasi exercitationem repellat qui ipsa sit aut",
  "body" : "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut ad\nvoluptatem doloribus vel accusantium quis pariatur\nmolestiae porro eius odio et labore et velit aut"
}, {
  "userId" : 1,
  "id" : 4,
  "title" : "eum et est occaecati",
  "body" : "ullam et saepe reiciendis voluptatem adipisci\nsit amet autem assumenda provident rerum culpa\nquis hic commodi nesciunt rem tenetur doloremque ipsam iure\nquis sunt voluptatem rerum illo velit"
}, {
  "userId" : 1,
  "id" : 5,
  "title" : "nesciunt quas odio",
  "body" : "repudiandae veniam quaerat sunt sed\nalias aut fugiat sit autem sed est\nvoluptatem omnis possimus esse voluptatibus quis\nest aut tenetur dolor neque"
}, {
  "userId" : 1,
  "id" : 6,
  "title" : "dolorem eum magni eos aperiam quia",
  "body" : "ut aspernatur corporis harum nihil quis provident sequi\nmollitia nobis aliquid molestiae\nperspiciatis et ea nemo ab reprehenderit accusantium quas\nvoluptate dolores velit et doloremque molestiae"
}, {
  "userId" : 1,
  "id" : 7,
  "title" : "magnam facilis autem",
  "body" : "dolore placeat quibusdam ea quo vitae\nmagni quis enim qui quis quo nemo aut saepe\nquidem repellat excepturi ut quia\nsunt ut sequi eos ea sed quas"
}, {
  "userId" : 1,
  "id" : 8,
  "title" : "dolorem dolore est ipsam",
  "body" : "dignissimos aperiam dolorem qui eum\nfacilis quibusdam animi sint suscipit qui sint possimus cum\nquaerat magni maiores excepturi\nipsam ut commodi dolor voluptatum modi aut vitae"
}, {
  "userId" : 1,
  "id" : 9,
  "title" : "nesciunt iure omnis dolorem tempora et accusantium",
  "body" : "consectetur animi nesciunt iure dolore\nenim quia ad\nveniam autem ut quam aut nobis\net est aut quod aut provident voluptas autem voluptas"
}, {
  "userId" : 1,
  "id" : 10,
  "title" : "optio molestias id quia eum",
  "body" : "quo et expedita modi cum officia vel magni\ndoloribus qui repudiandae\nvero nisi sit\nquos veniam quod sed accusamus veritatis error"
} ]

Response structure

Path Type Description

[].userId

Number

The userId of the user that made the post

[].id

Number

The id of the post

[].title

String

The title of the post

[].body

String

The body of the post

Get by Id

A GET request with a post id will return the post with that id if it exists in the list of greetings.

Example request

$ curl 'http://jsonplaceholder.typicode.com/posts/1' -i -H 'Accept: */*'

Example response

HTTP/1.1 200 OK
Date: Mon, 30 Jan 2017 14:39:43 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: __cfduid=d0a050a30093b4844e3015487d5071bb31485787183; expires=Tue, 30-Jan-18 14:39:43 GMT; path=/; domain=.typicode.com; HttpOnly
X-Powered-By: Express
Vary: Accept-Encoding
Access-Control-Allow-Credentials: true
Cache-Control: public, max-age=14400
Pragma: no-cache
Expires: Mon, 30 Jan 2017 18:39:43 GMT
X-Content-Type-Options: nosniff
Etag: W/"124-yv65LoT2uMHrpn06wNpAcQ"
Via: 1.1 vegur
CF-Cache-Status: HIT
Server: cloudflare-nginx
CF-RAY: 3295accb27ce3d1f-CPH
Content-Encoding: gzip
Content-Length: 296

{
  "userId" : 1,
  "id" : 1,
  "title" : "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body" : "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

Response structure

Path Type Description

userId

Number

The userId of the user that made the post

id

Number

The id of the post

title

String

The title of the post

body

String

The body of the post

Create a Custom Post

A POST request will create new posts.

Request Fields

Path Type Description

userId

Number

The userId of the user that made the post

id

Number

The id of the post

title

String

The title of the post

body

String

The body of the post

Example request

$ curl 'http://jsonplaceholder.typicode.com/posts' -i -X POST -H 'Accept: */*' -H 'Content-Type: application/json; charset=UTF-8' -d '{"userId": 1, "id": 101, "title": "Test Example", "body": "Example Body"}'

Example response

HTTP/1.1 201 Created
Date: Mon, 30 Jan 2017 14:39:44 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 87
Connection: keep-alive
Set-Cookie: __cfduid=d2e44ea9eb72da932e78c8a14cb69059f1485787184; expires=Tue, 30-Jan-18 14:39:44 GMT; path=/; domain=.typicode.com; HttpOnly
X-Powered-By: Express
Vary: Origin, X-HTTP-Method-Override, Accept-Encoding
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
X-Content-Type-Options: nosniff
Etag: W/"53-lBDK0/mZEBhcw16wxWbeUA"
Via: 1.1 vegur
Server: cloudflare-nginx
CF-RAY: 3295accc57c53d61-CPH

{
  "userId" : 1,
  "id" : 101,
  "title" : "Test Example",
  "body" : "Example Body"
}