Resource:User

From MapbenderWiki

This page is used to design the resource "User" and its representations.

See also Resource:Application and Resource:Service

We follow the steps described in Richardson's & Ruby's book "RESTful Web Services".

The resource "User" is more or less what is contained in the Mapbender database mb_user and used as the related object in the code base. We have split this data set into two resources:

• All users / the whole population of the Mapbender back end
• Individual user

For each kind of resource:

Contents 1 Name the resources with URIs 2 Expose a subset of the uniform interface 2.1 .../users/ 2.2 .../user/[id]/ 3 Design the representation(s) accepted from the client 4 Design the representation(s) served to the client 5 Integrate this resource into existing resources, using hypermedia links and forms 6 Consider the typical course of events: what's supposed to happen? 6.1 Create new user 7 Consider error conditions: what might go wrong? 7.1 Create new user

Name the resources with URIs

.../users/
.../user/[id]/

...where [id] is a variable describing each user individually

Expose a subset of the uniform interface

.../users/

Create, Read

Create

POST request with a JSON or XML document of a user including all mandatory (M) and optional (O) attributes:

• Name (M)
• Email address (M)
• phone / fax / ... (O)
• organization (O)
• ... (O)

Read

GET request returns all users (maybe need to implement paging). Several parameters can be queried (all optional?), for example:

name=[*string*]

id=[number]

email=[*string*]

... ?

.../user/[id]/

Read, Update, Delete

Read

GET request with no parameters.

.../user/[id]/

GET request with each single attribute appended as in

.../user/[id]/name
.../user/[id]/email
.../user/[id]/fax
...

Update

PUT request with JSON or XML document including all mandatory (M) and optional (O) attributes of a user:

.../user/[id]/[JSON] / [XML]

PUT request with one single attribute of a user:

.../user/[id]/name
.../user/[id]/email
.../user/[id]/fax
...

Design the representation(s) accepted from the client

GET request with no parameters.

.../user/[id]/

(see below: Returns a JSON or XML or HTML or (PDF?) document with all user information in one page.)

POST request with JSON or XML document including all mandatory (M) and optional (O) attributes of a user.

Returns 200 OK and a document (JSON, XML, HTML) with the URL of the new resource

.../user/[id]/

Design the representation(s) served to the client

JSON or XML or HTML or (PDF?) document with all user information in one page.

GET request with one single value, for example:

GET request .../user/[id]/name

Integrate this resource into existing resources, using hypermedia links and forms

Example: A request like

.../users/

would return a document with a list of links to resources of the type

.../user/[id]/

Consider the typical course of events: what's supposed to happen?

Create new user

To create a new user the "user agent" sends a JSON / XML document to the server containing at least name, email address (and password?) of the new user.

Consider error conditions: what might go wrong?

Create new user

User already exists (with same name and email):

HTTP response code xxx "already exists"; returned document contains link to existing .../user/[id]...

Parameters missing:

HTTP response code xxx "missing parameters"; returns document containing list of mandatory and optional parameters?!?