REST API GET method

Question

According REST API design recomendations, getting user by id must be

GET /users/{id}

How will look getting user by unique phone number?

GET /users/phone/{number}

or

GET /users/?phone=xxxxxxxxxxx

or

GET /phones/{number}/users

or anything else?

Or for example getting last user comments with limitation:

/users/{id}/comments/limit/{limit}

or

/users/{id}/comments/?limit='xx'

There are constraints or recomendations in such cases?

Which HTTP method is better to send request for making some actions (for example SMS sending).

Welcome to StackOverflow! Your question is currently too vague to provide a meaningful answer. Are you asking about a specific REST API or general approaches to API design? Please clarify the question and add additional tags if appropriate. — mfitzp, Feb 23 '15 at 12:37
It's a question of taste. Whatever approach you choose try to stick to it consistently through all resource urls. — Boris Pavlović, Feb 23 '15 at 12:40

score 1 · Answer 1 · edited May 23 '17 at 11:56

There are a lot of different aspects in your question, so I am picking some and hope the answer is somewhat helpful to you.

Generally speaking, a URI ist he unique identifier of a certain ressource. Further more, "good REST-API URIs" contain only nouns (to 'name' the resource), not verbs (what should be done with the resource). URI parameters may be used to parameterize the ressources representation, e.g. sorting or filtering.

In your example,

/users/{id}/?limit='xx'

would be a valid way to fetch a list of some sub-ressources (possibly the users comments), but here is nothing on the URI that refers to a specific property or sub-ressource (e.g. comments).

A more meaningful ressource URI would be

/useres/{id}/comments/?max=100&sort=asc

In this case, the first part (users/{id}/comments/) identifies the ressource, while the params are used to parameterize its representation. Proper URI's do not rely on URI params to uniquely identify ressources.

Filter criteria in the URI may be treated similiar. You could put them in parameters, but that may lead to problems with multiple and/or complex filters, e.g.

GET /useres/?phone=1234&phonemode=startswith&name=foo&namemode=contains

One way to do this could be to create a filter (maybe just temporarily) and then retrieving the filtered information with a subsequent GET request like this:

POST /users/filter
   name='mycomplexfilter'
   poperty='name'
   value='foo'
   mode='contains'        

GET /useres/filter/mycomplexfilter

Hope this helps to shed some light on the topic

[EDIT] See this summary for an explanation of the commonly used HTTP methods (aka verbs): Which HTTP methods match up to which CRUD methods?

See this question for a similiar answer.

Initiating a server sent notification (perhaps via SMS) should be requested using POST (e.g. to the ressource URI /notifications) with text and recipient in the payload. HTTP headers could be used to indicate the desired type of the notfication, while the HTTP status codes indicate the success of the sending attempt. Status code 201 indicates successfull sending of the message, returning also the URI for the newly created ressource.

Client request:

POST /notifications

recipient="+0049123456789"
text="this is the SMS text"

Server response:

201 - Created
Location: /notifications/9876

REST API GET method

1 Answers1