REST + JSON

After some experiences with WS saop in my job seem that people are more receptive to use Rest WS. I rather SOAP in legacy system manily because the wsdl is bounded and easy to document . Legacy systems are not flexible so you have to set all the rules beforehand. Legacy systems does not allow agile methods so the scaling out is not a something you have to have in mind. For that reason I think soap WS are more adapeted to PMI projects with traditional stages where the consitence is the key point but not avalaybilty. Nevertheless web and mobile applications are starting to change everything even in legacy systems. The amount of calls and data is doing that avalaiblity is becoming more and more important so caching and scaling out are things to really keep in mind and they are forcing us to set up solutions based in cloud and lightgweight protocols like Rest + JSON. This article is a collection of best practices and things to keep in mind to desing a Rest solution.

USE NOUNS NOT VERBS

I order to avoid a flooding of URI we should use nouns instead of verbs. If we have a entity called product easely your systems is going a need the whole CRUD operations.

\getProducts

\updateProduct 

\addProduct

\findProduct

Therefore you will have at least 4  new uri'. This is a fine graned approach. Another point of view ( Coarse graned) is tak just Product and to take advantage of the http methods to distinghis them.

Technicalle the solition is \products in plural. This is useful in scenarios when you can get object with only a http get call based in Id. Thant is to say GET <uri roo /products/3452352. Of course if you need set more parameters agregated  will be necesry  to do a POST with a json/xm object.

TABLE of HTTP methos

S.N.	HTTP Method, URI and Operation
1	GET http://localhost:8080/UserManagement/rest/UserService/users Get list of users (Read Only)
2	GET http://localhost:8080/UserManagement/rest/UserService/users/1 Get User of Id 1 (Read Only)
3	PUT http://localhost:8080/UserManagement/rest/UserService/users/2 Insert User with Id 2 (Idempotent)
4	POST http://localhost:8080/UserManagement/rest/UserService/users/2 Update User with Id 2 (N/A)
5	DELETE http://localhost:8080/UserManagement/rest/UserService/users/1 Delete User with Id 1 (Idempotent)
6	OPTIONS http://localhost:8080/UserManagement/rest/UserService/users List the supported operations in web service (Read Only)
7	HEAD http://localhost:8080/UserManagement/rest/UserService/users Returns only HTTP Header, no Body. (Read Only)

So you might thinkg there are a biyection correspondece betwen CRUD operations and http methods. HOwever the life is not as easy and

JSON 

Here some  adivices to write json

• Content-type application/json

• Notations follow JS standard or 'CamelCase' so avoid undersocres/hyphen  such as

load_produts. It is better loadProducts

• Dates, numbersStandar described in ISO 8601 so dates numbers and so on has already and standart
• Avoid href in json and set pagination with ofsset and size parameters if there are too many objectos to response. Of courser it only can be achieved if the WS has a sql or database store with a the possibility of opening a cursor.

RESTful security

Stateless is a goal to put your Webservice in MIcroServices or serverless platofrom so try to do sessionless services dooing autentification each reques if it is needed

Never autorizate based on URIs 

Use OAuth1 or 2 or SSL now TSL.

Use API Keys instead of user pwd

For Id's avoid sequential numbers. Good solutions is a UUId's