1

I want to create better RESTful APIs for mobile application. A simple example:

user model:
 - firstname
 - lastname
 - gender

services:
GET /users          => list of all users
POST /users         => create a new user
PUT /users          => update a bulk of users
GET /users/{id}     => one special users
PUT /users/{id}     => update a special user

It is better to create small interfaces like this instead of PUT /users/{id} ?:

PUT /usersFirstname/{id}
PUT /usersLastname/{id}
PUT /usersGender/{id}

On the one hand a mobile application only send the changed value and not the hole user model. But on the other hand I have many methods with nearly the same business logic and more maintenance.

Is there an best practice approach?

cassiomolin
  • 124,154
  • 35
  • 280
  • 359
cSteusloff
  • 2,487
  • 7
  • 30
  • 51

2 Answers2

3

REST resources

The key concept of REST is a resource. And that's how Roy T. Fielding defined a resource in the chapter 5 of his PhD dissertation (highlights are not present in the dissertation):

5.2.1.1 Resources and Resource Identifiers

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

[...]

REST uses a resource identifier to identify the particular resource involved in an interaction between components. [...]

A resource must have at least one URI to identify it. The URI is the name and address of a resource. Conceptually, you have a user resource hence you need a URI for it. So the following approach is a must go:

GET /users          # list of all users
POST /users         # create a new user
PUT /users          # update a bulk of users
GET /users/{id}     # one special users
PUT /users/{id}     # update a special user

And the following makes no sense when you have a user resource:

PUT /usersFirstname/{id}
PUT /usersLastname/{id}
PUT /usersGender/{id}

Performing partial updates

To deal with partial updates, use the PATCH HTTP verb. The PUT HTTP verb should be used to replace the entire resource with a new representation.

For partial updates, some approaches consider the fields of a main resource as sub resources. Then PUT can be used to replace the sub-resource with a new representation. Something like:

PUT /users/{id}/firstname
PUT /users/{id}/lastname
PUT /users/{id}/gender

I'm not saying that's a good or bad approach. That's just another approach to perform partial updates.

Retrieving partial representations

To retrieve a partial representation of a resource, use content negotiation or a query string parameter to filter the fields.

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359
1

Usually a web interface should be chunky not chatty thus you should probably post the whole user at once. This is also mentioned in the Microsoft API implementation guidance

Martin Brandl
  • 56,134
  • 13
  • 133
  • 172
  • Then I have to allow null values? In case the UI wants to change the gender but don't know the name at this point. – cSteusloff Jul 19 '16 at 08:57
  • You should send the complete user at once, containing all of its data if possible. You do want to make as few request as possible to reduce server resources. – Martin Brandl Jul 19 '16 at 09:03