REST API Best Practices

Base Url's
Only 2 base urls 1) collection & 2) singular
/dogs
/dog/ig

Use nouns & not verbs
/deals  - Groupon
/checkins - Foursquare

// do not have getDogs / getDogById
use HTTP Methods GET, POST, PUT, DELETE to define CRUD operations

How to handle associations
Get all dogs belonging to a owner 5678
eg: GET /owners/5678/dogs

Create a new new dog for a specific owner
eg: POST /owners/5678/dogs

Additional / optional parameters
GET /owners/5678/dogs?color=red&type=pet

Errors

1. code : use HTTP status codes
2. message : have message
3. more_info : have url for error docs; get more context; get help

Versioning

• have version at the start, do not have it in the middle 
• have highest level scope as much to the left as possible

eg:
/v1.2/dog/5678
Note: Do not release an API without versioning
why? FB moved from v1.2 to v1.3 and all apps supporting v1.2 broke

Partial Response

• If you only want some fields out of the whole data - want only id, name, type from an entire list of data

eg:
LinkedIn -> /people:(id,first-name,last-name,industry)
Facebook -> /saumilps/friends?fields=id,name,picture

Pagination

• have an offset & limit

eg:
/dogs?limit=25&offset=50

Formats
Spit more than one format

• /dogs.json
• /dog/1234.json
• Accept: application/json (pure RESTful way / in the header)
• ?type=json

Authentication
OAuth

REST vs SOAP

When to use REST ?

• Better performance
• Better scalability
• Reads can be cached
• Any browser can be used because the REST approach uses the standard GET, PUT, POST, and DELETE verbs
• Totally stateless operations: if an operation needs to be continued, then REST is not the best approach and SOAP may fit it better. However, if you need stateless CRUD (Create, Read, Update, and Delete) operations

When to use SOAP ?

• Asynchronous processing and invocation; if your application needs a guaranteed level of reliability and security then SOAP 1.2 offers additional standards to ensure this type of operation. Things like WSRM – WS-Reliable Messaging.
• Formal contracts; if both sides (provider and consumer) have to agree on the exchange format then SOAP 1.2 gives the rigid specifications for this type of interaction.
• Stateful operations; if the application needs contextual information and conversational state management then SOAP 1.2 has the additional specification in the WS* structure to support those things (Security, Transactions, Coordination, etc). Comparatively, the REST approach would make the developers build this custom plumbing.

WS-Security

While SOAP supports SSL (just like REST) it also supports WS-Security which adds some enterprise security features. Supports identity through intermediaries, not just point to point (SSL). It also provides a standard implementation of data integrity and data privacy. Calling it “Enterprise” isn’t to say it’s more secure, it simply supports some security tools that typical internet services have no need for, in fact they are really only needed in a few “enterprise” scenarios.

WS-AtomicTransaction

Need ACID Transactions over a service, you’re going to need SOAP. While REST supports transactions, it isn’t as comprehensive and isn’t ACID compliant. Fortunately ACID transactions almost never make sense over the internet. REST is limited by HTTP itself which can’t provide two-phase commit across distributed transactional resources, but SOAP can. Internet apps generally don’t need this level of transactional reliability, enterprise apps sometimes do.

WS-ReliableMessaging

Rest doesn’t have a standard messaging system and expects clients to deal with communication failures by retrying. SOAP has successful/retry logic built in and provides end-to-end reliability even through SOAP intermediaries.

Summary

In Summary, SOAP is clearly useful, and important. For instance, if I was writing an iPhone application to interface with my bank I would definitely need to use SOAP. All three features above are required for banking transactions. For example, if I was transferring money from one account to the other, I would need to be certain that it completed. Retrying it could be catastrophic if it succeed the first time, but the response failed.