Skip to content
Go REST

API reference
every endpoint, explained

Parameters, request examples and responses for users, posts, comments and todos.

Base URLhttps://gorest.co.in/public/v2

Posts

A post is written by a user and can have comments. Reading posts needs no token. Creating, updating and deleting do, and those records are visible only to your token.

The post object

idinteger
Unique identifier.
user_idinteger
The id of the user who wrote the post.
titlestring
Up to 200 characters.
bodystring
Up to 500 characters.
Endpoints
GET/public/v2/postsGET/public/v2/posts/:idPOST/public/v2/postsPATCH/public/v2/posts/:idDELETE/public/v2/posts/:idGET/public/v2/users/:id/postsPOST/public/v2/users/:id/posts
The post object
{
  "id": 2410,
  "user_id": 7012,
  "title": "Why we moved the test data to Postgres",
  "body": "The old setup was slow to reset. This one is ready in seconds."
}

List posts

GET/public/v2/posts

Returns a page of posts, the most recently changed first. Any field can be a filter.

Query parameters

pageintegeroptional
Page number. Starts at 1.
per_pageintegeroptional
Results per page, 1 to 100. Any other value gives 10.
idintegeroptional
Exact id.
user_idintegeroptional
Posts of this user.
titlestringoptional
Part of the title. Not case sensitive.
bodystringoptional
Part of the body. Not case sensitive.

The pagination headers come with the list. See Pagination below.

curl "https://gorest.co.in/public/v2/posts?page=1&per_page=10"
Response 200
[
  {
    "id": 2410,
    "user_id": 7012,
    "title": "Why we moved the test data to Postgres",
    "body": "The old setup was slow to reset. This one is ready in seconds."
  }
]

Get a post

GET/public/v2/posts/:id

Returns one post. A wrong id gives 404.

Path parameters

idintegerrequired
The id of the record.
curl "https://gorest.co.in/public/v2/posts/2410"
Response 200
{
  "id": 2410,
  "user_id": 7012,
  "title": "Why we moved the test data to Postgres",
  "body": "The old setup was slow to reset. This one is ready in seconds."
}

Create a post

POST/public/v2/posts

Needs a token. Returns 201 with the new post and a Location header, or 422 with a list of field errors. The user must exist.

Body parameters

user_idintegerrequired
The id of an existing user.
titlestringrequired
Up to 200 characters.
bodystringrequired
Up to 500 characters.

Only your token can see the new record.

curl -X POST "https://gorest.co.in/public/v2/posts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7012,"title":"Why we moved the test data to Postgres","body":"The old setup was slow to reset. This one is ready in seconds."}'
Response 201
{
  "id": 2410,
  "user_id": 7012,
  "title": "Why we moved the test data to Postgres",
  "body": "The old setup was slow to reset. This one is ready in seconds."
}

Update a post

PATCH/public/v2/posts/:id

Needs a token. Changes only the fields you send and returns the post. PUT does the same as PATCH. A record you cannot see gives 404.

Body parameters

user_idintegeroptional
The id of an existing user.
titlestringoptional
Up to 200 characters.
bodystringoptional
Up to 500 characters.
curl -X PATCH "https://gorest.co.in/public/v2/posts/2410" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"A shorter title"}'
Response 200
{
  "id": 2410,
  "user_id": 7012,
  "title": "A shorter title",
  "body": "The old setup was slow to reset. This one is ready in seconds."
}

Delete a post

DELETE/public/v2/posts/:id

Needs a token. Returns 204 with an empty body.

Path parameters

idintegerrequired
The id of the record.

If the table has fewer than 100 seeded records, the delete is refused with 422.

curl -X DELETE "https://gorest.co.in/public/v2/posts/2410" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 204
(empty body)

List the posts of a user

GET/public/v2/users/:id/posts

The same as the list above with user_id set from the path. Paging and the other filters work too.

Path parameters

idintegerrequired
The id of the user.
curl "https://gorest.co.in/public/v2/users/7012/posts"
Response 200
[
  {
    "id": 2410,
    "user_id": 7012,
    "title": "Why we moved the test data to Postgres",
    "body": "The old setup was slow to reset. This one is ready in seconds."
  }
]

Create a post for a user

POST/public/v2/users/:id/posts

Needs a token. The user id comes from the path, even if the body has another one. A missing user gives 422 with "must exist".

Body parameters

titlestringrequired
Up to 200 characters.
bodystringrequired
Up to 500 characters.
curl -X POST "https://gorest.co.in/public/v2/users/7012/posts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Why we moved the test data to Postgres","body":"The old setup was slow to reset. This one is ready in seconds."}'
Response 201
{
  "id": 2410,
  "user_id": 7012,
  "title": "Why we moved the test data to Postgres",
  "body": "The old setup was slow to reset. This one is ready in seconds."
}

Authentication

Reading needs no token. Writing (POST, PATCH, PUT, DELETE) needs one. Make a token on the tokens page after you log in, and send it in one of two ways.

Authorization: Bearer YOUR_TOKEN
A request header. This is the better way.
?access-token=YOUR_TOKEN
A query parameter, for quick tests in the browser.

A write without a token gives 401. A token that is wrong gives 401 "Invalid token", and an expired one gives 401 "Token expired". A token can only see the seeded records and its own.

Make a token

Pagination

Lists give 10 records a page. Use page and per_page (1 to 100) to change that. Details come in the response headers.

X-Pagination-Total
Total records that match.
X-Pagination-Pages
Total pages.
X-Pagination-Page
The current page.
X-Pagination-Limit
Records on a page.
X-Links-Previous
Full URL of the previous page. Empty on page 1.
X-Links-Current
Full URL of this page.
X-Links-Next
Full URL of the next page. Empty on the last page.

Rate limits

Each token can send 300 requests a minute by default. You can set it from 1 to 600 on the tokens page. Reads without a token have no limit. Calls with a token carry these headers. Past the limit you get 429 "Too many requests".

X-RateLimit-Limit
Requests a minute allowed for this token.
X-RateLimit-Remaining
Requests left now.
X-RateLimit-Reset
Seconds until you get more requests.

Errors and status codes

200 OK
The request worked. The record or list is in the body.
201 Created
A record was made. The Location header has its URL.
204 No Content
A delete worked. The body is empty.
304 Not Modified
Your cached copy (If-None-Match with the ETag) is still good.
400 Bad Request
A parameter is not valid text.
401 Unauthorized
The token is missing, wrong or expired.
404 Not Found
No such record, or it belongs to another token.
422 Unprocessable
A field failed a check. The body is a list of field and message.
429 Too Many Requests
The rate limit is used up.
500 Server Error
A fault on our side.
A 422 body 422
[
  { "field": "email", "message": "has already been taken" }
]

Format and testing

?delay=1500
On a GET, waits that many milliseconds first. The most is 5000. The answer has X-Simulated-Delay-Ms.
?force_status=503
Answers with that code. Allowed: 400, 401, 403, 404, 405, 415, 422, 429, 500 and 503.
.json or .xml
Add it to the path, or set the Accept header, to choose JSON or XML. JSON is the default.

Want to try a call now? Open the REST console.