CODEWITHSUNDEEP
apirest
Alex.Barylski
Alex.Barylski

Reputation: 2953

Some general restful api design questions

A few general design questions:

  1. Give the example here:

https://developers.google.com/+/api/latest/activities/list#nextPageToken

Why would the server return a token to retreive the next paginated result? Doesn't this break the idea of being stateless?

Why not just pass a MySQL like LIMIT name=value as the parameters? The server now has to return the number of pages I suppose...what am I missing?

  1. I read many but this one was of interest:

REST Web Services API Design

The second reply, offers the following examples.

GET http://api.domain.com/user/<id>
GET http://api.domain.com/users
PUT http://api.domain.com/user/<id>
POST http://api.domain.com/users
DELETE http://api.domain.com/user/<id>

Makes sense but why are there two plural resources? Could one not assume that if "user" is queried and was NULL or not provided that "all" was intended? Likewise for POST? If plural is for improved readability - why is there not a "users" resource for DELETE?

Ultimately, I understand REST to mean...representation of a single resource - using HTTP verbs (GET, PUT, POST, DELETE) to essentially manage that resource - similar to CRUD.

EDIT | Lastly I also wanted to ask why Google API sends the API version in the URI instead of using HTTP headers? Is there a reason? For backwards compat with older clients?

Comments?

Upvotes: 0

Views: 1035

Answers (1)

Timothy Shields
Timothy Shields

Reputation: 79621

Why would the server return a token to retrieve the next paginated result? Doesn't this break the idea of being stateless?

Using this kind of mechanism for paginated result sets is completely standard and does not break the idea of being stateless. Consider the following example.

Suppose GET /users?after=<after> (where after is optional) is supposed to return the list of all users in a paginated fashion, say <= 4 per page.

The first request a client makes is GET /users with a response that might look like the following (formatted as JSON).

{
    "users": [ "alex", "bob", "carter", "dan" ]
    "more_after": "dan"
}

In this example, the more_after property designates there may be more users left in the user list. So the client then requests GET /users?after=dan and gets a second response that looks like the following.

{
    "users": [ "edward", "frank" ]
}

The absence of the more_after property designates that this is the last page of users.

Now the question is: was the "dan" token used as the page separator something that breaks the "statelessness" property we want? Clearly the answer is no. The server doesn't have to remember anything between the two GET requests. There's no concept of a session. Any state that needs to persist between the two GET requests exists only client-side - that's the important distinction. It's completely acceptable - and often required - to have the client persist state between calls to the service.

Upvotes: 2

Related Questions