Integration Shift - Http as a Uniform Contract

REST, an architecture style, when properly applied achieves a technology architecture that closely resembles the web. Although Restful API doesn’t mandate the usage of HTTP as a transport protocol, however in practice, http is the default choice for all restful apis.

REST leverages following elements of HTTP protocol  to provide uniform contract:

Uniform Resource Identifier (URI): HTTP URI provides a way of identifying resources within a service inventory. Generic Syntax for URIs is as follows:

{scheme}://{authority} {path}?{query}#{fragment}—->http://onlinestore.com/api/products?type=“toys”#page1

In this example, http is the scheme, online store.com is the authority,/api can identify an inventory or functional context , /products is the path that identifies the product resource within the inventory.

Some of the design guidelines while constructing resource identifiers:

- Path shouldn’t start with the variable part. For eg: avoid http://onlinestore.com/api/{products}

- Trailing slashes can indicate the collection of resources. For eg: “http://onlinestore.com/api/products/“ can give the list of products.

- Standardize the name of query params across the list of services or Service Inventory

- Use URI params for identifying the entity record rather than query param.

- Explicitly specify the query params that is need while constructing URIs. For eg: http://onlinestore.com/api/products{?type, price-range}

Method enables request- response communication with resources through URIs that includes methods, headers, response codes. 

Methods: Http provides set of generic methods such as GET, PUT, POST, DELETE, HEAD & OPTIONS that can be leveraged to interact with the resources and perform tasks like retrieving, creating, updating or deleting a resource. Service implementation at the server side controls what methods are allowed for a resource.

Headers: Http headers provides an additional information and can provide the metadata on how message should be processed by intermediary layers along the message path. They can be classified in several ways:

- According to their context: General Header,(Connection, Date, Cache-Control),  Request Header (Accept, Accept-Charset),  Response Header (Location, ETag , Age) , Entity Header (Allow, content-length, mime-type)

- According to Usage Category:

  1) Authentication (WWW-Authenticate, Authorization)

  2) Caching (Age, Cache-Control, Expires)

  3) Client Hints (Accept-CH)

  4) Conditionals (Last-Modified, ETag)

  5) Connection Management (Connection, Keep-Alive)

  6) Content - Integration (Accept, Accept-Charset)

  7) Controls (Expect, Max-Forwards) 

Response Codes: Http responses has a status code which specifies whether the request is successfully completed. They are grouped into five classes:

1) Information Responses (100 - 199) {100  Continue, 101 Switching Protocol}

2) Successful Responses (200 - 299) {200 OK, 201 Created, 202 Accepted}

3) Redirection Messages (300 - 399) {300 Multiple Choice, 301 Moved Permanently, 302 Found}

4) Client Error Responses (400 - 499) {400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found}

5) Server Error Responses (500-599) {500 Internal Server Error, 501 Not Implemented, 502 Bad Gateway, 503 Service Unavailable}

Media Types: This helps further specify the type of data that is be processed by an api. Media Type has the syntax  (type “/“ subtype *( “;” parameter). Some of the common media types are 

text/ plain; charset=utf-8 for simple representation such as integer or string data.

application/xhtml+xml for more complex lists, tables, human readable text, hypermedia links

application/xml for well-formed xml data that may or may not be schema specific

application/json for key-value pairs that can be parsed as javascript objects.

APIs usually processes “application” media type which can further qualified as vendor specific custom media types. Custom media types are usually identified with the notation:

application/vnd.organization.type+supertype (application/vnd.com.onlinestore.product+xml)

In the next post, I will write about some RAML / Swagger used for generating API specs & tooling around it.