REST API design is relatively new for me and trust me it is much more than designing Class with few methods. It becomes all the more difficult for someone with RPC background. Here you need different mind set all together.
Rest is different Architecture Style and there is no well-defined specification for the same. Rest is being very well adopted and has emerged over the period since 2000. While defining highly scalable API we really need to think about lot from non-functional requirements like scalability, manageability availability, extendibility, backward compatibility etc..
Overall, the thing to keep in mind is that REST is about exposing resources through URIs, not services through messaging interfaces. REST, in theory, is not limited to the web, but for the purposes of this blog post we assume to be discussing REST in the context of the world-wide web.
In order to design Rest APIs we need to simply answer following four questions.
1. What are the URIs? [“resources"]
a. Identify Resources (Generally nouns in the system) and break your problem down into the types of resources you want to manipulate. Try to list all the resources you could possibly need at this step. e.g Student, Order, LineItem etc..
b. Two places to consider when looking for potential resources are collections and search interfaces. A “collection of resources” may, in itself, be a whole new resource.Search interface will always return collection of resource meeting the search or filter criteria.
c. The thing to remember is that each resource should have its own URI.
2. What’s the format? ["representation"]
a. Decide what the representations are going to look like ( XML & JSON are most common exchange formats for RestFul Services )
3. What methods are supported at each URI? [GET,PUT,POST,DELETE]
a. Identifying methods to support seems relatively straightforward. Think about Create, Retrieve, Update and Delete operations on the identified resource. Based on application operation on the resource, GET, PUT, POST, DELETE could be decided
b. There is generally no confusion about GET and DELETE ( Retrieve, Delete operations )
c. POST is used for non-idempotent creation. This is when entity identifier is not passed during creation but needs to be generated by the back-end. For instance, news student creation operations are non-idempotent. Entity identifier (primary key) for the created entity is returned in the response, if entity creation was successful. Since the operation is non-idempotent, issuing it twice will create two similar entities.
d. PUT is used for idempotent creation. PUT should be used whenever resource unique id is known and passed during creation. General philosophy here is if resource does not exist it will be created and if exist then it will be updated.
e. Typically each entity type only supports either idempotent or non-idempotent creation. Usually most content is non-idempotent and is created with HTTP POST.
4. What status codes could be returned?
a. 200 OK: Success!
b. 304 Not Modified: There was no new data to return (think: cache).
c. 400 Bad Request: Invalid Request. Error message will be returned to provide further details.
d. 401 Unauthorized: Authentication credentials were missing or incorrect.
e. 403 Forbidden: Valid request that was refused. Attempt to access a resource that the client does not have permission to. Error message will be returned to provide further details.
f. 404 Not Found: The URL requested is invalid or the resource requested, such as a story or a user, does not exists.
g. 406 Not Acceptable: Returned when parameters passed are correct in theory and individually, but when combined can not be satisfied because the combination makes no sense (e.g. cart_id from one user is used with a user_id from another user). If possible, an error message will be returned to provide further details.
h. 500 Internal Server Error: Something went wrong on server side
i. 503 Service Unavailable: Servers are offline for maintenance or went down under load (oops).
Important REST Design Principles
1. RESTful HTTP approach
Proper RESTful APIs extensively utilize HTTP Protocol. Usage of HTTP methods for CRUD, standard HTTP response codes, common HTTP headers and Mime Types is a common practice.
Using HTTP is not enough, Using HTTP in a standard way is most important!
2. Every resource has identifier
On the Web, there is a unified concept for IDs: The URI. URIs make up a global namespace, and using URIs to identify your key resources means they get a unique, global ID. Each resource in CVP program viz. vehicle, user etc. will have identifier. VIN is unique identifier to identify vehicle.
RESTful URL Format RESTful APIs are semantic, resource-centric and have a general structure which looks something like the following:
http://api.myservice.com/{ver}/{lang}/{resource_type}/{resource_id}.{output_format}?{filters and api_key as arguments}
where:
{ver} indicates the version of the API and allows changing API syntax/behavior without breaking legacy clients (not necessarily providing “new” functionality for them, however). Usually version can be omitted, and it defaults to the latest stable version of the API.
{lang} in multilingual APIs, is a two-letter ISO abbreviation for a language, e.g. “en” for English, “es” for Spanish etc. Typically defaults to “en” for English, if ommited.
{resource_type} is the name of the resource, e.g.: user, story, cart, line item etc.
{resource_id} is a unique identifier of the resource. Can be numeric or alpha-numeric (e.g. in usernames). Often sequence numbers of the internal database schemas are used as identifiers, however usage of universally unique identifiers (UUIDs) leads to better-designed APIs.
{output_format} - Commonly used to let API know which format response is requested in: xml, html, json, bson, rss, atom are some of the common formats implemented. Frequently format can also be indicated using the HTTP Accept-headers.
3. Do not overuse POST: POST is in some senses the “most flexible” of HTTP’s methods. It has a slightly looser definition than the other methods and it supports sending information in and getting information out at the same time. Therefore there is a tendency to want to use POST for everything. You should only use POST when you are creating a new URI. Simply asl yourself whether you are using POST to do something that is really a GET, DELETE or PUT, or could be decomposed into a combination of methods.
4. Link things together
Each resource also gets links to its sub resources or its associations with other resources. GET request for Student also gets link to associated Address of that Student.
Resources in RESTful URLs are often chained. For instance, to access an item in a user’s order the resource part of the URL may look like: “user/2323/order/54234/line_item/73321″. Important thing to remember about resource chaining is that it represents a hierarchy: the line item belongs to the order and the order belongs to the user.
5. Stateless communication
REST mandates that state be either turned into resource state, or kept on the client. In other words, a server should not have to retain some sort of communication state for any of the clients it communicates with beyond a single request. The most obvious reason for this is scalability the number of clients interacting would seriously impact the server’s footprint if it had to keep client state. (Note that this usually requires some re-design
6. Idempotent Operation
Requests that use GET, PUT and DELETE methods are idempotent according to HTTP specification, meaning that they can be called multiple times consecutively without changing the status on the back-end. POST method does not guarantee to be idempotent special attention is needed for POST method.
7. Avoid actions in URIs.
This follows naturally from the previous point. But a particularly pernicious abuse of URIs is to have query strings like “someuri?action=delete”. First, you are using GET to do something unsafe. Second, there is no formal relationship between “action=” convention is something specific to application. REST is about driving as many “application conventions” out of the protocol as possible. Also avoid using verbs in URI
8. Sessions are irrelevant.
There should be no need for a client to “login” or “start a connection.” HTTP authentication is done automatically on every message. Client applications are consumers of resources, not services. Therefore there is nothing to log in to! So for example, while placing an order on a REST web service, we don’t create a new “session” connection to the service. Rather we ask the “order creator object” to create you a new order.
9. Request Caching
REST encourages caching of requests that can be cached, to minimize network bandwidth utilization. APIs should implicitly or explicitly mark response to a request as cacheable or non-cacheable. If a response is cacheable, then clients are encouraged to locally cache it and reuse data for later, equivalent requests. HTTP headers are typically used to label cacheable content and indicate the permitted duration of cache.
No comments:
Post a Comment