The document discusses REST API design principles and best practices. It explains that RESTful services embrace HTTP features like caching, security, and scalability. Key REST design principles include: using HTTP methods explicitly, making services stateless, exposing hierarchical URI structures, and transferring JSON or XML content. URI patterns should use nouns for resources and HTTP methods explicitly. Versioning, response codes, and the uniform interface should also be applied.

1. REST API Design

2. What is REST
• The move towards RESTful services is ultimately about moving towards a programmable Web, one where we can
replace humans with application code. It’s essentially about applying the principles of REST to the domain of Web
services. Ultimately, designing RESTful services is no different than designing RESTful Web applications except we
need to facilitate removing humans from the equation.
• When you design a RESTful service, you have to think about things differently. You no longer focus on designing
methods. Instead, you focus on the resources that make up your system, their URIs, and their representations.
RESTful services conform to the HTTP uniform interface – you simply need to decide which of those methods you’ll
support for each resource. In order to remove humans from the equation, you’ll need to use resource representations
that are easy to programmatically consume.
• Unlike traditional RPC-style frameworks that attempt to hide communicat ion details, RESTful services actually embrace
HTTP and its features and fully take advantage of them as much as possible. As a result, RESTful services
automatically receive the valuable benefits inherent in the Web platform including the built-in security features,
caching controls, compression, and ultimately improved performance and scalability. And best of all, you don’t have to
wait for it – the Web platform is ready today – complete with products, infrastructure, and helpful resources available
for immediate use.

3. Design principles
● Use HTTP methods explicitly.
REST supports GET,POST,PUT,DELETE. Metadata information HEAD/OPTION
● Be stateless.
REST Web service clients would send complete, independent requests; that is, to send requests that include all data needed to
be fulfilled so that the components in the intermediary servers may forward, route, and load-balance without any state being held
locally in between requests. it helps in highly distributed system
● Expose directory structure-like URIs.
A URI is not merely a slash-delimited string, but rather a tree with subordinate and superordinate branches connected at nodes
it helps in organizing services as well as defining a single path.
● Transfer XML, JavaScript Object Notation (JSON), or both.
Many times it ideally supports ATOM.

4. Design styles
● Use Noun for defining resource
● For single value, follow pattern {id}
● Either use plural or singular noun. Many people use singular for single value. Use plural for ALL.
● Use HTTP operation explicitely.
Anti pattern To make GET?POST etc as the part of the uri.
● Adding version control to entities
● Defining proper response code
● Applying the uniform HTTP interface.

5. Continued..
URI patterns
HTTP URI RPC operation
PUT users/{username} createUserAccount
GET users/{username} getUserAccount

6. Content type
Representation Requested via... Notes
JSON Requested via one of the following:
● application/json in the HTTP
Accept header
● .json extension
XML Requested via one of the following:
● application/xml in the HTTP
Accept header
● .xml extension
JSONP Requested via one of the following:
● application/json in the HTTP
Accept header andjsonp-callback
query parameter
● .json extension and jsonp-callback
Only available on GET. The returned
content type MUST
beapplication/javascript.

7. Reference
● Microsoft MSDN library
● Atlasian developer guideline
● DZone Architecture section