taliferro

Find Instead of Search

Life is Not Linear. Why Is your mobile experience?

There is a reason it is becoming more challenging to generate steadily increasing technology revenue. With a plethora of systems available and a superabundance of information, the mobile user experience is not in alignment with OSS/BSS systems. Regardless of how sophisticated modern day platforms have become, reliance on the old desktop user experience is reaching its limits. How people use data is not in alignment with current systems.

It’s time for a new paradigm! One that exponentially improves technology ROI.

Today’s long list search display paradigm does not work nor does it provide a pleasant user experience. Too much data is crammed into small screens. While search algorithms are becoming more sophisticated, the way results display simply are not optimized for current mobile devices. Not only does this old model leave the user out of the equation, but also heavily relies on algorithms to do all the work. By giving users more control via how they search, by allowing them to provide context, search results can dramatically improve. Context is critical in honing down a search to exactly find what you want.

Search companies know the list model is broken. Some search engines, for example, try to improve search by providing website images within search lists. While this is helpful, we are still operating from the old search list paradigm – but only adding some visuals. To transform search, the idea is not to do the same thing only better, but to think entirely different about how to search. With mobile device users growing, most would agree that the list model has become inefficient and cumbersome.

Our approach is different!

Our upcoming platform effortlessly cascades multiple levels of context and allows users to hone down their search to specific, useful information quickly. By providing multiple levels of context via a dynamic, visual display for mobile devices, users control how deep they want to go, and the results are highly personalized.

Stay tuned for more information on this revolutionary way to “find” instead of “search.” The world’s 1st “Find” platform.

REST Due Diligence Guidelines and Checklist

Practical guidelines and a comprehensive checklist help to keep a team’s focus on best practices and tasks, which are important for developing an appropriate and successful REST design.

Overview Statement
This document describes best practices related to exposing web services via REST. Although the focus is primarily on REST, the guidelines may expand to include SOAP and other technologies in the future.
REST resource design principles, exposed to external parties are captured in this document. Descriptions of the design life-cycle and design considerations are intended for an audience of REST architects, designers, and authors as well as other groups involved with REST implementation and testing. Even though the guidelines focus on external exposure, also use the practices for internal implementations to produce a company-wide consistent interface.

Further, this document defines requirements and offers a roadmap for projects developing REST resources targeted for external exposure outside of OSS and BSS systems. For example, possible REST Program design time portals such as (http://rest.taliferro.com).

REST development guidelines provide for the exposure of functions that external developers can use in their applications; for example advertising, call control, messaging, payment, contacts and other functions Taliferro may make available. Adherence to guidelines and requirements is strongly recommended.

Rationale
The guidelines seek to ensure that interfaces exposed to external sources are consistent, coherent, and compliant with all relevant best practices, policies, and regulations, even when interfaces are developed by different groups within Taliferro, or by partners on behalf of Taliferro.
Equally important, the guidelines prevent Taliferro from deploying a mish-mash of REST resources that are poorly organized and developed to different interface standards and practices. Moreover, following the guidelines prevent Taliferro from incurring legal and financial liability and public embarrassment as a result of inappropriate REST practices.

Issue/Problem
This document establishes requirements and guidelines in several areas, including:
• Style guidelines governing naming resources and data elements to maximize consistency, minimize confusion, and enhance discovery.
• Organization of resources into a taxonomy or folder system for easy browsing by external developers.
• Versioning strategies to reduce development and deployment costs to both external developers and Taliferro.
• Technical requirements associated with the implementation of middleware; such as, RESTful Web Services that are in demand by the worldwide development community.
• Security, privacy, legal, and regulatory requirements applicable to REST resources.
• Governance to support the approval, versioning, and cataloging of REST resource’s designs and implementations.

Representational State Transfer (REST)
Representational State Transfer (REST) is a software architectural style for distributed hypermedia systems like the World Wide Web. The term originated in a doctoral dissertation, Architectural Styles and the Design of Network-based Software Architectures (2000) by Roy Fielding.
REST is not a standard but an architectural style. Therefore, following REST means adhering to a style rather than a standard. The REST architectural style has six constraints as denoted by Roy Fielding in his doctoral dissertation.

The constraints are:
Uniform Interface
A prevailing doctrine in software development is to create a common interface. By applying this fundamental concept, architecture is simplified, and visibility between software and data is enhanced.
Decoupling responsibilities encourages independence among different software layers. Today, developers do not want to accept decoupled responsibility and are unwilling to accept a degradation in efficiency. This tradeoff corrupts REST. The result creates one-and-two-off REST resources, which are nothing more than server applications with URL pointers.

Often SOAP is disguised as REST, by creating a URL pointer to a server side SOAP application. As Roy Fielding states, “In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components.”
(a) Identification of resources
Each resource has an identification or address by using URIs
(b) Manipulation of resources through URI representation
The client can manipulate the resource by using the resource’s representation
(c) Self-descriptive messages
Each message contains the necessary information to process the resource
(d) Hypermedia as the engine of application state (HATEOAS)
(e) State transitions performed by hypermedia are dynamically identified by the server

Stateless
Client context is stored on the server. Each request is self-contained and does not rely on any information stored on the server.

When you type in a web address in your browser that address is a pointer to information. If you like the information you see in your web browser, chances are you want to create a reference or a bookmark. The bookmark allows the return to the same address in another period, to refer to the same information.
On the web, there is dynamic content and static content. Dynamic content is built on-the-fly when a user visits a URL. Static content does not change, which is important to understand to grasp the concept of stateless.
When a URL address (web resource) is stateless, the address you reference is not dependent on any previous action. Stateless web resources are called at any time with the expectation that its current “state” is not dependent on any other action.

Dynamic web addresses, are usually stateful and require additional information or some previous action to understand what type of content to create. A good example of a stateful URL is an Internet shopping cart. When purchasing an item on the Internet, you enter your name, address, and payment for the item. After all information is submitted, a confirmation page displays. During each data entry screen, the information you enter must pass from one screen to another. Otherwise, there is no way to determine what you ordered or where to send the item. Thus, a stateful mechanism (a session) keeps your information nicely organized so that as you proceed from one page to the next the current “state” of the order process is known.

In REST, the URL that you go to should be stateless. The web resource URL the browser or some other program uses does not require a session, or any additional information to access the requested information. The web resource is static, meaning you receive current information.

Cacheable
Responses must also convey to the client whether it is cacheable or not, which allows the client to determine if the data needs to be refreshed.

The resource is stored in the web browser or application’s program cache. A cacheable resource can be bookmarked for later retrieval.

The combination of a web resource being stateless and cacheable provides a benefit to programs and web browsers to:
– expedite processing
– reduce read-write conflicts
– reduce the reliance on the Internet
– reduce bandwidth usage
– reduce server load
– make applications scalable
– improve overall network efficiency

Client-Server
The client and server have clear separation of responsibilities, which allows portability of client code because the separation is straightforward.
Furthermore, the client/server constraint is intended to separate processing instructions. For example, computer systems operate more efficiently when processing is dedicated to either graphics, data, or logic.
In the client/server paradigm, the user interface is separated from where the data resides and how the data is processed. Thus, a client focuses all the computer’s processing power on how the screen looks, but not on the accuracy of the information.

Layered System
The server may have layers, but the client does not need to know and interfaces with the server as one entity. A layered architecture allows software designers to encapsulate code and logic to a specific domain, resultantly, isolating developers and users from underlying software complexity. Layering software does have its drawbacks in that; latency begins to creep in, slowing down once nimble systems.
When using layers, the effort is to encapsulate legacy software isolating deeper layers and legacy clients. Further, layering simplifies software collections and systems by moving responsibilities infrequently used to a common broker. A brokering mechanism improves system scalability. Brokering also provides load balancing across networks.

Code-on-Demand (Optional)
The last constraint Roy Fielding speaks of is the optional code-on- demand concept. Code-on-demand “…allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.

Allowing features to be downloaded after deployment improves system extensibility. However, it also reduces visibility, and thus is only an optional constraint within REST”. It’s good that Mr. Fielding made this an optional constraint, especially in light of how technology changes and evolves.

Applets downloaded to a client for execution via HTTP requests are all but extinct, since the advent of Apps via tablets. Other reasons code-on-demand is an optional constraint depends on context, security, and privacy issues where the constraint may not be viable. Nonetheless, it is disappointing to observe how REST development today in many cases, ignores fundamental principles. Instead of having applications run on the client, applications are run on the server defeating the purpose of distributed processing.

Distributed processing is the intent of this optional constraint; however, the industry implements the old CGI paradigm (and SOAP) and creates URI pointers to applications running on a server. The aforementioned is NOT REST, and is NOT a principle of REST architectural style.

RESTful Web Services

A RESTful Web Service is an architectural style that conforms to:
• A hierarchical URI structure
• A uniform interface consisting of HTTP verbs
• HTTP transport

REST Architecture Elements

Data Elements

Another REST architecture concept is the state of data elements. When a user clicks a link, a server retrieves information and displays the information in a browser, in most cases. Retrieving information is no different from other distributed processing patterns. In distributed processing, data, processing logic, and display are separate and served by computers that specialize in either displaying information, processing information, or storing information.

Currently, the Internet allows developers to:
– format data for display on the server and send it to a browser
– send data and display format framework or engine
– forward data and a data description allows a rendering agent to format properly.

Each option has pros and cons. However, what REST tries to do is provide aspects of all three options focusing on a shared understanding of data, and metadata, within a certain scope.
REST transfers a representation of a resource based on a mutual understanding of the data. The representation is derived from the source and remains hidden behind the interface. REST fits the mobile paradigm perfectly because the representation of the data is sent along with instructions for a rendering engine.

The processing separation still fits a client-server style without overloading the server. REST allows for the encapsulation and advancement of software interfaces.

Resources and Resource Identifiers
Any data identified individually or as a group is a resource. Another way to think of a resource is to think of information as a hierarchy. Some resources are static and always return the same elements. Other resources frequently change, or the value is unknown until runtime. REST requires that the resource definition stays as static as possible because the naming and hierarchy is what distinguishes one resource from another.
This static state of the web in the context of URLs allows caching and bookmarking. The bookmarking gives generality to the underlying data without explicitly specifying an implementation.

Using URLs as pointers supports late data binding and content negotiation. A resource identifies a data set. A REST connector establishes a generic interface for changing the value of the resource. Like images and HTML pages, care should be taken in maintaining resource links. When pages move on the Internet, servers return a 404 error or page not found. With REST, time should be allocated to ensure links are performing as expected because there could be one too many applications using the resource. Invalid resources trigger errors in programs using the links.

Representations

Components

Roy Fielding defines REST components as software that performs actions on a resource. REST uses a resource’s current representation and state, which is transferred between components. In the same manner images and documents are transferred across the Internet.
Consider the representation as the data and metadata describing the data. Metadata, sometimes described as data-about-data, is a name-value pair:
– Name = the semantics
– Value = the representation of name

Data Control

Control relates to how data is handled by software; such as, what is requested or what is the meaning of a response. Control also helps define the expected behavior of connectors; such as, if the data can be modified.

Data Format

Data format equals media/mime type. What type of data is represented? Video, audio, Word document, Keynote document, etc. Any messages should include the representation, so the developer’s code knows how to process a resource. Multiple resources transferred as one or better known as composite resources, should contain the data format for each element.
The data format will have a dramatic effect, depending on which media type chosen. Remember, the resource is transported across the Internet, and not all connection speeds are equal. Consider also that the data may need rendering on some devices, so great care should be taken with the amount of data and data format used.

Connectors

A REST connector is a way of transferring resource representations. The connector is a communication interface that provides a clean separation of implementation. The connector directs the network communication for a component. The information is shared across many requests for efficiency.
All REST interactions are stateless, which means each request must encompass all of the compulsory information to understand the request. What REST tries to accomplish with this directive is:
– scalability, by allowing a request to stand on its own
– parallel processing of requests because each is independent
– aid brokering by allowing federated systems to peek at a request and either combine or re-route the request
– caching capabilities, all information will be available for processing
Connectors are the client, server, and cache. The difference is that the client initiates a request, and the server acts upon the request. A component can contain a client and server connector(s).
The cache connector is located on the client or server to quickly respond to a request. REST is about efficient use of the network. REST tries to balance transparency with network efficiency, instead of assuming transparency is always available.
A cached resource should determine if the most up-to-date information is provided.

Authentication

If user authentication is needed for a resource then the resource should only be cacheable by a non-shared cache. Components have the capability to override this behavior by including the type of control data previously mentioned; such as if the resource, is cacheable, non-cacheable, or cacheable for only a limited time.
Resolver
A resolver turns a resource identifier into a network address. You can think of the resolver as a type of DNS. With a DNS, names such as www.microsoft.com are turned into IP Addresses 283.4.34.343. This IP address is the physical location on the web, and the name is its alias. Resolvers improve the longevity of resources via redirection. The drawback, a resolver creates a layer of latency. The latency may be long or short depending on the implementation.

Tunnel

A tunnel is a secure, limited connection between two points and is included as a REST connector because REST components can switch to a tunnel connection, and then back to an active connection. For example, an HTTP proxy that communicates with a remote server using various protocols.

Components

A middle layer is needed to route a request to a server or route a response to the client. Components act as the middle layer to forward or translate requests and responses. Otherwise known as a proxy, the intermediary on the client hardware provides an interface to services, translation, performance, and security protection.
A component is a broker on the network that provides an interface to other services, translation, performance or security enforcement. There is a difference between a proxy and a gateway; also, the client determines when to use a proxy.

What are resources?

A resource is a data structure or thing like a noun. The resource can represent an actual data structure that is implemented, or an abstract view of that data structure. The name of a resource should be a noun because it is a thing. For example, a contact or a message. Moreover, a resource should not describe any action performed. In other words, the resource should not be construed as some action, or Remote Procedure Call (RPC), like SOAP. The outcome of using an HTTP verb with the resource, is similar to RPC, but it should not be viewed or designed as such.
The resource has a data structure and address (URL) to access the data structure. A developer can access the resource by using an HTTP verb (i.e. GET, POST, etc.) on the URL to that resource. The HTTP verb used depends on the action required; such as create, retrieve, update, or delete. The REST resource should be designed so that all HTTP verbs interact with a resource.

Resource Description and Discovery

A resource should be described using well-known and descriptive formats, (i.e. WADL, RAML, Swagger, SMD or RESTdoc). The aforementioned formats expose to developers ways to automate consumption of the REST resource. A resource is also used by internal teams, testing and developing. In like manner, a descriptive format is returned in an HTTP OPTION request.
The entity body should be described using XSD for XML and JSON schema for JSON payloads. XSD helps a developer validate the entity body sent or returned.

General URL Syntax

There are many different methods for resource access; and many schemes for describing the location of such resources. The generic syntax for a URL provides a framework for establishing new protocol schemes.
URLs are used to locate resources, by providing an abstract identification of the resource location. Once the URL locates a resource, a system may perform a variety of operations on the resource, as might be characterized by words such as access, update, replace, and find attributes. In general, only the access method needs to be specified for any URL scheme.

Resource URLs

The URL is the address of a resource with the following characteristics:
• Brief but descriptive.
• The URL is short and adequately describes the resource.
• Avoid acronyms to prevent ambiguities.
• A resource is a thing. The resource name is a noun.
• Each path element is actionable; or what I call resource restrictive, unless there is a policy restriction.
• Each path element is accessible. For example, if a parent path element does not return anything in a GET, then the path element is not needed.
• For consistency, collections are plural nouns, and the child path element should be a singular representation of the collection, usually an ID.

Design Considerations

Overall, designing a REST implementation requires considerable thought:
1. Alignment with company governance to ensure consistency across Taliferro
2. RESTful best practices as defined by Taliferro
3. Consistency across all REST implementations including previous versions, if applicable
4. Consistency with general developer community conventions and standards
5. Feedback from the developer community. (Developer feedback is important to ensure the REST implementation is easy to use.)
Several other standards in addition to those contained in this document are used:
• Uniform Resource Locators (RFC 1738)
• HTTP Standards (rfc7230, rfc7231, rfc7232, rfc7233, rfc7234 andrfc7235)
Note: To fully understand the Due Diligence Guidelines one must comprehend the standards mentioned above and referenced throughout the guidelines.

Example Design

Return a collection of messages (collection is plural, and no unnecessary hierarchies)
GET /messages

Return a particular message identified by {messageId)
GET /messages/{messageId}

Return the parts (in the case of multipart messages) of a message)
GET /messages/{messageId}/parts

Return a particular part associated with a particular message.
GET /messages/{messageId}/parts/{partNo}
Actions on Resources (Verbs)

Create

When creating a new resource, the name of the resource is given by the client or server. If the client specifies the resource name, then use a PUT verb. If the server assigns the name of the resource, then use a POST verb. In either case, HTTP returns a status 201 with a location header parameter of the value specifying the location of the resource.
One benefit of allowing the server to assign the resource name is to avoid naming conflicts. If the client chooses the name, then both the client and server will have to implement logic to handle checking for conflicts in names (i.e. if the name already exists).

Retrieve

A resource uses GET to retrieve a representation of the resource. The request contains no body, but may contain headers. Use the GET method to get collections or individual resources. The desired representation format is implicitly or explicitly (accept header given).

Update

An update to a resource occurs when one or more attributes of an existing resource require changes. Typically, changes use the HTTP verb PUT. However, there are times when a POST is used. Below are the conditions for which HTTP verb to use:
PUT – Send full resource representation in the entity body. In other words, replace not update.
POST – Subset of a resource’s parameters requires updates. The full resource is not included in the entity body; however, the server needs to be aware of the partial update, and the resource needs to be different from any other operations (i.e. Create) that uses the POST verb.
In either case, the full path to the resource must be specified in the URL. To reiterate, the path that points to the specific resource must be provided, it is recommended for updates to return an HTTP 204 with an empty entity body. Any returned metadata is contained in the entity headers. In some instances, there may be a need to return an entity body. For example, if the values of any of the parameters in the response are different from what was specified in the request, then the entity body of the full resource should be returned.

Delete

Use the HTTP verb DELETE when deleting a resource. For a successful deletion, an HTTP 204 status code is returned. Sometimes it is needed to delete multiple resources in one request because the process may be too cumbersome for a developer to delete individual resources if a large set requires deletion. In this case, the DELETE is executed against the collection, with a query parameter specifying which individual resources should be deleted.

Hierarchy

Hierarchies are beneficial to show the relationships between data elements. Hierarchies:
• Enforce Referential Integrity
• URL makes understanding data relationships easy
• Supports troubleshooting
• Allows for easy report generation and statistical analysis

Entities

The HTTP entity is the actual HTTP message, which consists of headers and the body. Each part is used to convey different types of information. The headers are separate from the body with a CRLF (Carriage Return Line Feed).

Headers

Use headers to convey metadata, secure data that cannot reside in the URL, or data related to the HTTP protocol. All custom headers use a convention that identifies headers as custom. For example, the convention was to use the “x”- prefix in the name of a header. This convention has been deprecated though it is still used to identify a custom header when the custom header parameter never becomes part of a published standard. To further namespace the custom header parameter, prefix the parameter name with x-taliferro to signify that it is custom and belongs to Taliferro.
Below is an example of headers that are part of a GET. The three lines after the first line are HTTP headers, which are key/value pairs separated by a colon (:). The HTTP header parameter names are case-insensitive; however, the values of the parameters are not.

Common Request Headers

Accept Type of content adequate for the response
Authorization Information required for request authentication
Cache-Control Directives that MUST be obeyed by all caching mechanisms
Content-Length Length of the message (without headers)
Content-Type Media type of the entity-body sent to the recipient
Date Current date and time according to the requester
If-Match Used with a method to make request conditional
If -None-Match Used with a method to make request conditional
Host Specifies the Internet host and port number of the resource requested
Server Information about the software used by the origin server to handle the request

Common Response Headers

Content-Length Length of the message (without headers)
Content-Type The media type of the entity-body sent to the recipient
Connection Allows sender to specify options for a particular connection
Date The current date and time according to the responder
ETag Current value of the entity. Reflects changes only to object, not the metadata
Host Specifies the Internet host and port number of response
Server Information about the software used by the origin server

Header Examples

GET /contacts?limit=10&offset=1 HTTP/1.1

host: rest.taliferro.com

accept: application/json

authorization: Bearer xyz123456789

 

 

Good REST resources are cacheable.

Caching allows applications to reference a resource or composite resource later, which reduces network traffic, latency, and increases user response.

If cacheable, use an expiration.

 

Good

HTTP/1.1 200 Ok

content-type: application/xml

content-length: 120

date: Mon, 29 Apr 2013 21:44:55 GMT

ETag: “e6811cdbcedf972c5e8105a89f637d39”

Expires: Mon, 29 Apr 2013 22:44:55 GMT

Cache-Control: max-age=3600

 

Bad

HTTP/1.1 200 Ok

content-type: application/xml

content-length: 120

date: Mon, 29 Apr 2013 21:44:55 GMT

 

Request ID

The REST resource response returns request ID for troubleshooting purposes

 

Good

HTTP/1.1 200 Ok

content-type: application/xml

content-length: 0

date: Thu, 04 Jun 2013 02:51:59 GMT

x-taliferro—request-id: 47cd254-e0d1-44a9-af61-1d6d86ea6b77

 

 

Bad

HTTP/1.1 200 Ok

content-type: application/xml

content-length: 0

date: Thu, 04 Jun 2013 02:51:59 GMT

Body

Use the body to pass resource representation because it is the actual data that represents the resource. As such, naming parameters identify the resource in a definitive way. The parameter is encapsulated in a main parent object parameter, and the parameter name identifies the resource as a thing, which does not convey an action. For example, if the resource is a contact, then the parent object is named contact.

<?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>

<contact>

<firstName>John</firstName>

<lastName>Smith</lastName>

</contact>

 

{

“contact”:{

“firstName”: “John”,

“lastName”: “Smith”

}

}

The request and response bodies should support JSON, XML, and URL form encoded. The formats are constructed to take advantage of each format’s strength, and not necessarily a one-to-one mapping between JSON and XML. For example, lists or arrays are represented differently in XML and JSON. Moreover, XML has element attributes that may represent the data better than having a separate element. JSON does not, but the XML representation does if it makes sense.

Representations have a parent object that encapsulates the data and provides better structure, as well as adheres to XML form. Equally important, ensure there are not any unnecessary hierarchy levels.

JSON

JSON is lighter in weight than XML and has become more popular in recent years. JSON is the default representation format on many platforms when the Accept header parameter is not specified.

JSON has 4 primitive data types and 2 structure types: • Primitive: String, Number, Boolean and Null. The String type is quoted while the Number and Boolean are not quoted. Null is empty.

A JSON schema benefits developers and internal teams.

XML

For XML entity bodies, the XML declaration is used in XML body, and returned in every XML response. Nevertheless, some platforms are more forgiving if the XML declaration is not sent in a request from a developer.

An XML schema (XSD) is available for the benefit of developers and internal teams.

Content Negotiation

Content negotiation is a mechanism that allows a client to negotiate what content is returned in the response from the server. The client has the option to request the content type of the response and/or the content encoding of the response. The former uses the accept HTTP header to request the content type, while the latter uses accept- encoding HTTP header.

Accept

The REST resource allows clients the ability to request a specific content type best suited for the client application.

Defining MIME and MEDIA types are good REST practices. An application may need a video type because of the platform type. The application may need video such as, Quick Time video for iPad.

Good

GET /files/22323232 HTTP/1.1

host: rest.taliferro.com

authorization: Bearer 38C2399A23999

accept: audio/wav

 

Bad

GET /files/22323232 HTTP/1.1

host: rest.taliferro.com

authorization: Bearer 38C2399A23999

Using the accept HTTP header makes it possible for the client to request different representations of a resource from the same URI. The most common representations are JSON and XML. The requester indicates to the service which representation of the resource should be returned. For HTTP, this is achieved by including the Accept HTTP header in the request. The values specified must adhere to the HTTP standard Accept processing.

The accept header also has quality weights (0.0-1.0) applied to a mime type, using the accept-param “q”. If the “q” accept-param is not supplied, then it is assumed to be 1.0. For example:

accept: application/xml;q=0.8, application/json

Here, the q value for application/json is assumed to be 1.0, so that takes higher precedence over application/xml. Specify the mime type as a range by using the * (asterisk) character.

accept: application/*, */*

Where */* accepts anything, the more specific mime type takes precedence over a general one. So, in this case, application/* takes precedence over */*.

Accept: text/plain; q=0.5, text/html,

text/x-dvi; q=0.8 , text/x-c

Which says send me text/html or text/x-c, but if they are not available send me text/x-dvi and if that doesn’t exist send me text/plain.

We can do this for say Payment in which our accept header would look like:

Accept: application/xml; schema=Payment; q=0.5, application/xml; schema=PaymentSummary, application/xml; schema=PaymentDesktop; q=0.8, application/xml; schema=PaymentMobile

 

Caveats to the HTTP accept handling:

  1. A long-standing practice among many platforms is the accept parameter should have a default mime type. For most REST implementations, the default is application/json. So, if the Accept parameter is not provided the default mime type is used.
  2. The HTTP standard mentions that if a value passed in the accept parameter cannot be found, then the server SHOULD send a 406 (not acceptable) response. However, there is a note in the HTTP status code 406 which states, HTTP/1.1 servers are allowed to return responses which are not acceptable. In such cases, the REST resource should return the default content-type (i.e. application/json), if one exists and only respond with a 406 if there happens to be no default.

Accept-Encoding

Using the accept-encoding HTTP header makes it possible for the client to request different content encoding of a resource from the same URI. A common example: the client requests the response payload to be compressed. The rules for processing the request are very similar to the section above.

Data types

Data types specify an order to give developers guidance on how to process the data. Data types should not change or dynamically generate. For example, if a parameter is an array, the parameter remains an array even if there is only one element for a particular instance of that parameter, such as:

“name”:[“John”]

The parameter is not flattened as a String.

XML has many more data types, but are often not needed. Therefore, data types are minimized unless necessary.

Date

Any date parameters should conform to ISO8601

  • Most programming languages can handle this format, so it should be easy for the developer to handle using standard libraries
  • It is also human readable, so if you are looking at logs or troubleshooting, it helps to recognize without any conversion
  • ISO8601 supports several variants and satisfies most needs. For example:

– 1994-11-05T08:15:30-05:00 (with timezone offset) – 1994-11-05T13:15:30Z (expressed in UTC)

– 1994-11-05 (abbreviated)

Status codes and error codes

Status codes and errors inform a developer of the outcome of a request and signal to the developer the necessary action that needs to take place. Sometimes only the HTTP status code is needed to convey that information. Other times more information is required in the response entity.

When more information is needed, the header or body of the response entity should contain the information. In the case of a successful response (201) to a creation, the response entity body contains a representation of the created resource. Moreover, in the case of an error response, the entity contains additional information if needed, and that information contains a specific error code. Currently, there are 2 error categories following the GSMA/OMA convention, with service error and policy error concepts.

Note: When the server issues an error that shows internal server information (e.g. stack traces), the information is not returned to the client.

Below are response codes pertinent to good REST design. The HTTP status code gives an initial indication to a developer the outcome of the request. The use of HTTP status codes is well known and documented.

200 OK

The request for the REST resource has succeeded. The information returned with the response is dependent on the method used in the request, for example:

  • GET an entity corresponding to the requested resource is sent in the response;
  • HEAD the entity-header fields corresponding to the requested resource are sent in the response without any message-body;
  • POST an entity describing or containing the result of the action;
  • TRACE an entity containing the request message as received by the end server.

201 Created

The request to create a REST resource is fulfilled and results in a new resource. The newly created resource is referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead. 1

A 201 response MAY contain an ETag response header field indicating the current value of the entity tag for the requested variant just created.

202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.

The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent’s connection to the server persist until the process is completed. The entity returned with this response

SHOULD include an indication of the request’s current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.

203 Non-Authoritative Information

The returned meta information in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy. The set presented MAY be a subset or superset of the original version. For example, including local annotation information about the resource might result in a superset of the meta information known by the origin server. Use of this response code is not required and is only appropriate when the response would otherwise be 200 (OK).

204 No Content

The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta information. The response MAY include new or updated meta information in the form of entity-headers, which if present SHOULD be associated with the requested variant.

If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent’s active document view, although any new or updated meta information SHOULD be applied to the document currently in the user agent’s active view.

The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.

205 Reset Content

The server has fulfilled the REST request and the user agent SHOULD reset the document view which caused the request to  be sent. This response is primarily intended to allow input for actions to take place via user input, followed by a clearing of the form in which the input is given so that the user can easily initiate another input action. The response MUST NOT include an entity.

206 Partial Content

The server has fulfilled the partial GET request for the resource. The request MUST have included a Range header field indicating the desired range, and MAY have included an If-Range header field to make the request conditional.

The response MUST include the following header fields:

– Either a Content-Range header field indicating the range included with this response, or a multipart/byte ranges Content-Type including Content-Range fields for each part. If a Content-Length header field is present in the response, its value MUST match the actual number of OCTETs transmitted in the message-body.

– Date

– ETag and/or Content-Location, if the header would have been sent in a 200 response to the same request

– Expires, Cache-Control, and/or Vary, if the field-value might differ from that sent in any previous response for the same variant

If the 206 response is the result of an If-Range request that used a strong cache validator the response SHOULD NOT include other entity-headers. If the response is the result of an If-Range request that used a weak validator, the response MUST NOT include other entity-headers; this prevents inconsistencies between cached entity-bodies and updated headers. Otherwise, the response MUST include all of the entity-headers that would have been returned with a 200 (OK) response to the same re- quest.

A cache MUST NOT combine a 206 response with other previously cached content if the ETag or Last-Modified headers do not match exactly, see 13.5.4.

A cache that does not support the Range and Content-Range headers MUST NOT cache 206 (Partial) responses.

300 Multiple Choices

The requested REST resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information is provided so that a user (or user agent) can select a preferred representation and redirect its request to that location.

Unless it was a HEAD request, the response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content- Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice MAY be performed automatically. However, this specification does not define any standard for such automatic selection.

If the server has a preferred choice of representation, it SHOULD include the specific URI for that representation in the Location field; user agents MAY use the Location field value for automatic redirection. This response is cacheable unless indicated otherwise.

301 Moved Permanently

The requested REST resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. Clients with link editing capabilities ought to automatically re-link references to the Request-URI to one or more of the new references returned by the server, where possible. This response is cacheable unless indicated otherwise.

The new permanent URI SHOULD be given by the Location field in the response. Un- less the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).If the 301 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

Note: When automatically redirecting a POST request after receiving a 301 status code, some existing HTTP/1.0 user agents will erroneously change it into a GET request.

302 Found

The requested REST resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. This response is only cacheable if indicated by a Cache-Control or Expires header field.

The temporary URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).

If the 302 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

Note: RFC 1945 and RFC 2068 specify that the client is not allowed to change the method on the redirected request.

However, most existing user agent implementations treat 302 as if it were a 303 response, performing a GET on the Location field-value regardless of the original request method. The status codes 303 and 307 have been added for servers that wish to make unambiguously clear which kind of reaction is expected of the client.

303 See Other

The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource. The 303 response MUST NOT be cached, but the response to the second (redirected) request might be cacheable.

The different URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).

Note: Many pre-HTTP/1.1 user agents do not understand the 303 status. When interoperability with such clients is a concern, the 302 status code may be used instead, since most user agents react to a 302 response as described here for 303.

304 Not Modified

If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code. The 304 response MUST NOT contain a message-body, and thus is always terminated by the first empty line after the header fields.

The response MUST include the following header fields:

– Date, unless its omission is required

If a clockless origin server obeys these rules, and proxies and clients add their own Date to any response received without one (as already specified by [RFC 2068]) caches will operate correctly.

– ETag and/or Content-Location, if the header would have been sent in a 200 response to the same request

– Expires, Cache-Control, and/or Vary, if the field-value might differ from that sent in any previous response for the same variant

If the conditional GET used a strong cache validator the response SHOULD NOT include other entity-headers. Otherwise (i.e., the conditional GET used a weak validator), the response MUST NOT include other entity-headers; this prevents inconsistencies between cached entity-bodies and updated headers.

If a 304 response indicates an entity not currently cached, then the cache MUST disregard the response and repeat the request without the conditional.

If a cache uses a received 304 response to update a cache entry, the cache MUST update the entry to reflect any new field values given in the response.

305 Use Proxy

The requested resource MUST be accessed through the proxy given by the Location field. The Location field gives the URI of the proxy. The recipient is expected to repeat this single request via the proxy. 305 responses MUST only be generated by origin servers. Note: RFC 2068 was not clear that 305 was intended to redirect a single request, and to be generated by origin servers only. Not observing these limitations has significant security consequences.

306 (Unused)

The 306 status code was used in a previous version of the specification, is no longer used, and the code is reserved.

307 Temporary Redirect

The requested resource resides temporarily under a different URI. Since the redirection MAY be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. This response is only cacheable if indicated by a Cache-Control or Expires header field.

The temporary URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s) because many pre-HTTP/1.1 user agents do not understand the 307 status. Therefore, the note SHOULD contain the information necessary for a user to repeat the original request on the new URI.

If the 307 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

400 Bad Request

The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

401 Unauthorized

The requested REST resource requires user authentication. The response MUST include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The client MAY repeat the request with a suitable Authorization header field.

If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user SHOULD be presented the entity that was given in the response, since that entity might include relevant diagnostic information. HTTP access authentication is explained in “HTTP Authentication: Basic and Digest Access Authentication” [43].

402 Payment Required

This code is reserved for future use.

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.

404 Not Found

The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

405 Method Not Allowed

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource.

406 Not Acceptable

The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. Unless it was a HEAD request, the response SHOULD include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice MAY be performed automatically. However, this specification does not define any standard for such automatic selection.

Note: HTTP/1.1 servers are allowed to return responses which are not acceptable according to the accept headers sent in the request. In some cases, this may even be preferable to sending a 406 response. User agents are encouraged to inspect the headers of an incoming response to determine if it is acceptable.

If the response could be unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions.

407 Proxy Authentication Required

This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy. The proxy MUST return a Proxy-Authenticate header field containing a challenge applicable to the proxy for the requested resource. The client MAY repeat the request with a suitable Proxy-

Authorization header field HTTP access authentication is explained in ”HTTP Authentication: Basic and Digest Access Authentication.”

408 Request Timeout

The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by an earlier (third-party) request, the server might use the 409 response to indicate that it can’t complete the request. In this case, the response entity would likely contain a list of the differences between the two versions in a format defined by the response Content-Type.

410 Gone

The requested REST resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) SHOULD be used instead. This response is cacheable unless indicated otherwise.

The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event is common for limited-time, promotional services and for resources belonging to individuals no longer working at the server’s site. It is not necessary to mark all permanently unavailable resources as ”gone” or to keep the mark for any length of time – that is left to the discretion of the server owner.

411 Length Required

The server refuses to accept the request without a defined Content-Length. The client MAY repeat the request if it adds a valid Content-Length header field containing the length   of the message-body in the request message.

412 Precondition Failed

The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. This response code allows the client to place preconditions on the current resource meta information (header field data) and thus prevent the requested method from being applied to a resource other than the one intended.

413 Request Entity Too Large

The server is refusing to process a request because the request entity is larger than the server is willing or able to process. The server MAY close the connection to prevent the client from continuing the request. If the condition is temporary, the server SHOULD include a Retry- After header field to indicate that it is temporary and after what time the client MAY try again.

414 Request-URI Too Long

The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret. This rare condition is only likely to occur when a client has improperly converted a POST request to a GET request with long query information, when the client has descended into a URI ”black hole” of redirection (e.g., a redirected URI prefix that points to a suffix of itself), or when the server is under attack by a client attempting to exploit security holes present in some servers using fixed-length buffers for reading or manipulating the Request-URI.

415 Unsupported Media Type

The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

416 Requested Range Can’t Be Satisfied

A server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If- Range request-header field. (For byte-ranges, this means that the first- byte-position of all of the byte-range-spec values were greater than the current length of the selected resource.)

When this status code is returned for a byte-range request, the response SHOULD include a Content-Range entity-header field specifying the current length of the selected resource. This response MUST NOT use the multipart/byte ranges content- type.

417 Expectation Failed

The expectation given in an Expect request-header field could not be met by this server, or, if the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server.

419 Authentication Timeout (not in RFC 2616)

Not a part of the HTTP standard, 419 Authentication Timeout denotes that previously valid authentication has expired. It is used as an alternative to 401 Unauthorized in order to differentiate from otherwise authenticated clients being denied access to specific server resources.[citation needed]

422 Can’t Process Entity

The request was well-formed but was unable to be followed due to semantic errors.[4]

423 Locked

The resource that is being accessed is locked.[4]

428 Precondition Required

The origin server requires the request to be conditional. Intended to prevent “the lost update” problem, where a client GETs a resource’s state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict.”

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate limiting schemes.

431 Request Header Fields Too Large

The server is unwilling to process the request because either an individual header field, or all the header fields collectively, are too large.

451 Unavailable for Legal Reasons

Defined in the internet draft ”A New HTTP Status Code for Legally-restricted Resources”.[21] Intended to be used when resource access is denied for legal reasons, e.g. censorship or government-mandated blocked access. A reference to the 1953 dystopian novel Fahrenheit 451, where books are outlawed.

500 Internal Server Error

The server encountered an unexpected condition which prevented it from fulfilling the request.

501 Not Implemented

The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.

502 Bad Gateway

The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response. Note: The existence of the 503 status code does not imply that a server must use it when becoming overloaded. Some servers may wish to simply refuse the connection.

504 Gateway Timeout

The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

Note: Note to implementers: some deployed proxies are known to return 400 or 500 when DNS lookups time out.

505 HTTP Version Not Supported

The server does not support, or refuses to support, the HTTP protocol version that was used in the request message. The server is indicating that it is unable or unwilling to complete the request using the same major version as the client. The response SHOULD contain an entity describing why that version is not supported and what other protocols are supported by that server.

Multiple Data Formats

Accept: application/xml; schema=mms

Content-type: application/xml; schema=mms

Pagination

Pagination refers to retrieving partial data, mostly due to payload size constraints. The pagination is used as a filter or query; hence pagination should be implemented as query parameters. To standardize pagination across REST resources, the following parameters are used to remain consistent: limit Specifies the upper limit number of items returned in the response. Must be 1 or greater. The default value varies depending on the service and constraints on that service. Offset specifies the offset from the beginning of the ordered set of items. Must be 0 or greater. The default should be 0 because 0 is the most common offset used and signifies there is no offset, and should start at the beginning.

Query Parameter Type Description
$filter string You can filter the results using a filter expression syntax. The following fields and operators are supported
$limit string The number of entities to return.
$offset string The number of entities to skip.

 

GET /customers?limit=10&offset=1 HTTP/1.1

host: rest.taliferro.com

accept: application/json

authorization: Bearer xyz123456789

Sorting Data

Some REST resources choose to sort order of the data returned if the data represents a collection. Data is sorted by a particular parameter value, and sometimes the direction of the sort is specified. The following parameters are used to remain consistent across REST resources: order specifies the sorting order of the output. The acceptable values for parameters:

  • ASC : Ascending order (default)
  • DESC : Descending order.

orderBy Specifies the parameter name for ordering the output. If multiple parameters are used, then those parameters are separated by commas.

GET /customers?order=ASC&orderBy=firstName HTTP/1.1

host: rest.taliferro.com

accept: application/json

authorization: Bearer xyz123456789

Filtering

Some REST resources need filtering, if a subset of the data is needed. When filtering, the parameter and a value for that parameter are used to filter the data related to that parameter value. Therefore, filtering represents a type of query, and query parameters are used unless otherwise restricted due to privacy or security concerns.

Property Supported operators Supported functions
MessageFrom  ge, le, eq, ne, gt, lt substringof, startswith, endswith

 

Below is an example of how to implement filtering using the “isIncoming” parameter:

GET /messages?filter=MessageFrom eq ‘Mike’ HTTP/1.1 Host: rest.taliferro.com

authorization: Bearer xyz123456789

accept: application/json

Response parameter selection

In some cases where the response representation is significant, it may be desirable to have the ability to specify the response parameter returned in the response. For example, a header parameter is sent in the request to indicate to the platform which parameters to return. The example below can take 2 possible values: shallow, {comma separated list of parameter names}. If the value is blank, or not included in the request, then the assumption is that the full representation is returned. If shallow is specified, then a predefined subset of parameters are returned.

Example with shallow parameter:

GET /contacts/eb765de8-8080d3b674c4 HTTP/1.1

Host: rest.taliferro.com

authorization: Bearer xyz123456789

accept: application/json

x-fields: shallow

 

HTTP/1.1 200 OK

date: Thu, 04 Jun 2010 02:51:59 GMT content-length: 870

{

“smallContact”: {

“contactId”: “09876544321”,

“formattedName”: “JOHN JAMES DOE”,

“firstName”: “JOHN”,

“middleName”: “JAMES”,

“lastName”: “DOE”,

“prefix”: “SR.”,

“suffix”: “II”,

“nickName”: “TEST”,

“organization”: “ATT”,

“phone”: {

“type”: “HOME”,

“number”: “2223335555”

},

“address”: {

“type”: “WORK”,

“preferred”: “TRUE”,

“poBox”: “3456”,

“addressLine1”: “345 140TH PL NE”,

“addressLine2”: “APT 456”,

“city”: “REDMOND”,

“state”: “WA”,

“zipcode”: “90000”,

“country”: “USA”

}, “email”: {

“type”: “WORK”,

“emailAddress”: “XYZ@ABC.COM”

},

“im”: {

“type”: “AIM”,

“imUri”: “ABC”

} }}

 

Asynchronous Responses

Occasionally, a REST resource may not return within the same transaction. The resource is returned to the application when the resource is available. The resource can return in a callback, or the application can retrieve the resource later based on status. On a request, a callback URI is provided so that the resource returns to the application. For asynchronous requests, HTTP status 202 Accepted is returned.

For instance, in a callback example the application sends a POST request to create a new resource and sends the data necessary to create the resource, along with the callback URI so that the platform sends the asynchronous response back.

The REST platform responds to the POST request with an HTTP 202 Accepted, indicating to the application that the request is successfully accepted but still processing. There is also a correlation ID returned so that a developer can use the ID to correlate the message to the callback.

Once the request is processed and ready, the response for the resource creation is sent to the callback URI. When an error occurs during the processing of resource creation, an error message is sent to the callback URI.

The application responds with HTTP 200 to complete the HTTP transaction.

Nonetheless, it is possible to provide a developer with a way to poll for the created resource. Furthermore, instead of having the REST platform push the newly created resource when ready, the application polls for the newly created resource to check its readiness.

Another example polling

  • The application sends a POST (or possibly PUT) request to create a new resource, and sends the data necessary to create the resource. If the platform allows both polling and callback, then a callback URI is sent as well so that the REST platform sends the resource when ready.
  • The REST platform responds to the POST request with an HTTP 202 Accepted, indicating to the application that the request is successfully accepted but still processing. Included also is the resource location URI and/or an identifier to track the new resource. Periodically, check the resource status.
  • An HTTP 404 is returned if the resource is not yet ready. Optionally, including an availability time stamp tells the application when the resource is ready.
  • Finally, when the resource is ready, the latest GET fetches the resource.

The response includes Resource representation.

Resource Creation

When creating a new resource, use either POST or PUT HTTP verb

Use POST if the server decides the resource name, such as

POST /collection

Use PUT if the application determines the name of the resource

PUT /collection/theresource

The response must include HTTP status code 201, with the HTTP header location set to the URI of the newly created resource:

If the created resource is an exact match to the data sent in the request, then the response should not include an entity body. However, if there are extra parameters or if parameters are set differently than requested, the resource representation is returned in the entity body, and the HTTP POST verb is usually used. To the contrary, it is possible to use a PUT.

Resource Comparison

There may be a scenario where a particular record exists and a compare operation is performed on that existing record to validate its contents. The action is typically executed when a third-party app already has some data or is collecting data from the end user and needs to validate the authenticity of that data, which is not confused with a filter operation or a retrieval operation.

Follow the compare method when data is not sent due to security/privacy concerns requiring the need to perform a compare. Although this particular requirement imitates a filter operation, it is not a filter operation because we already know the record exists, and we are trying to compare the record contents.

Use the HTTP GET verb where a query string parameter passes as field name equals the value to be compared. The resulting response contains an HTTP status code 200 if the record is found. The response body contains the list of fields along with their values in the requested format. The response header contains a special header “x-nonMatched” with a comma separated list of values for all the fields that do not match. The special header is not present if all the fields properly match. This special header contains all the fields if no fields match, and the HTTP status code is 204 without any body. The response parent element should match the request resource name.

Deletion

One resource

Technically speaking, only delete a single resource, for example:

DELETE /items/1 HTTP/1.1

A successful response is indicated by a HTTP 204 (No Content).

Multiple resources

The capability for a developer to delete a single resource is supported in REST implementation. However, sometimes there needs to be a way to delete multiple resources at once. A convenience for the developer, deleting multiple resources at once is supported by using query parameters to identify resources for deletion, as such:

DELETE /items?ids=1,5,7,8 HTTP/1.1

If the IDs represent sensitive information (i.e. Taliferro phone numbers) do not place that information in the query string. Place the resource IDs in the header, as such:

DELETE /items HTTP/1.1

x-resourceIds: 1,5,7,8

Requirements for Existing Applications

Existing REST implementations that do not conform to the requirements specified in this document are grandfathered. The requirements are brought into compliance when modified, and where it makes business sense to do so. Note: Significant changes in legislation or corporate policy may force changes to existing REST Resources on a case-by-case basis.

Requirements for New Applications

All new and modified REST resources within a defined scope conform to the requirements in this document.

Industry Standards

Description: Some REST resources may be required to conform to industry standards such as OMA OneAPI or WAC. A determination is made by the business unit sponsoring REST resources development.

Requirements:

REST resources required to conform to a specific industry standard comply with the requirements of this document except where conflict exists with an industry standard. Where a conflict exists, the industry standard prevails.

Where resources contain path elements that consist of several words concatenated together with no intervening delimiters, each word after the first in the path element are capitalized for easier readability. Path elements with abbreviations and acronyms conform to general naming requirements for use of abbreviations and acronyms in names.

Data Element and Attribute Requirements:

Where XML is used, element and attribute names start with a small letter and follow the general naming requirements of this practice.

Where JSON is used, field and object names start with a small letter and follow the general naming requirements of this practice.

Middleware and Data Standards

Description: REST resources should support standards desired by the development community.

General requirements are provided below, and specific requirements are provided in the sections that follow:

REST resources use the HTTPS protocol; not HTTP.

To lessen the impact of minor version changes, clients are advised to use neither XML schema validation nor {is this ending correct?}

JSON schema validation.

URLs support the use of fully qualified domain names, which means support is provided for domain names terminated with a period (e.g., https://rest.taliferro.com.:9090/…).

Checklist Overview

The Due Diligence Checklist ensures that important REST criteria are reviewed, analyzed, and accepted.

Functional Behavior

Notes:

A server restart is a good stateless test. REST architecture requires adherence to the core principles as outlined in Fielding’s dissertation. However, some guidelines have evolved from the implementation of such services in various contexts. Hence, most guidelines regarding REST MAY not derive from REST principles, but the technical issues that make an architecture usable.

Query strings are not necessarily wrong. However, when implementing a clean REST interface the resource path is definitive. Query parameters imply an augmented state. “Stateless” is a key constraint of REST. Further, the query parameter casts doubt over whether or not the resource is stateless. Use query strings to derive such information, but only when necessary.

For REST services requiring a POST or PUT, provide a schema to specify the response format, and when using microformats like JSON, share the specification with consumers.

REST is a lightweight architecture that can be used for integration purposes.

Data Considerations

¨             Is the data portable?

¨             Is system context considered for a particular client?

¨             Are there any developer groups to consider that can be divided?

¨             Is data cacheable? Are the resources’ data cacheable?

¨             Are response formats specified using a schema?

¨             No empty are documents returned in case of an error?  [is this correct}

¨             Is the functionality for delivery or aggregation into existing websites? Services are exposed with XML and consumed by HTML pages without significantly refactoring the existing website architecture. [is this correct}

Project Considerations

¨ Is a risk assessment necessary?

¨ Are all stakeholders considered?

¨ Are there any forms or documentation for reference about how to use the implementation?

¨ Have the number of client applications expected been considered?

¨ Has the rate of growth been anticipated?

¨ Have the effects of projected performance been considered?

¨ Is a growth trend available?

¨ Realistic implementation timeline?

¨ In case of an emergency, has maximum downtime been considered?

¨ Is there a fallback plan?

¨ Are there environment limitations for deployment?

¨ Has bandwidth been considered?

¨ Will the resource always return a response document?

¨ Will the response return a request ID for troubleshooting purposes?

REST Checklist

Completed Task Notes
¨ Not converting SOAP services into REST using a one-to-one match There is not a one-to-one match, different thinking and strategy required
¨ Not using verbs in the URL resource definition REST has already defined these verbs PUT, POST, DELETE, GET. A resource name should be a plural noun
¨ Following the REST design pattern /{plural-noun}/{ID} /{plural-noun}/{ID}/ . . . etc, (in other words collection based and the ID within the collection see Twillio for a good REST design
¨ Using non resource-restrictive URI Adding words to the URI path that yield no results or are there just to describe the data (don’t add meta data to the resource path)
¨ REST resource is stateless
¨ REST resource is static resource Data structure should be the same always and not vary
¨ Not using REST as function calls
¨ Not using abbreviations as names Names should be clear and understandable to non-tech people
¨ Not returning empty responses Even on an error a descriptive response should be returned
¨ Identifying the data entities and not focusing on functions
¨ Integration considered with other projects or application
¨ REST resource should be controllable by the caller/client Not by Taliferro
¨ The REST resource name is a noun and easy to recognize
¨ The REST resource does not use spaces in the name Hyphens or underscores
¨ The “/” in the URI should express a parent-child relationship
¨ The REST resource only uses the query string when necessary Can the query parameter pass through the body of the message?
¨ The REST resource does not derive metadata from the URI
¨ The REST resource is client side cacheable
¨ The REST resource is explicitly using HTTP actions (PUT, POST, DELETE, GET)
¨ The response returns a request ID for troubleshooting purposes
¨ The resource does not use server-side scripting technology (file extensions .jsp, .php, .asp)
¨ The resource is lowercase
¨ Is the response payload simple, human readable, and connected?
¨ Will the resource allow clients the ability to request a specific content type best suited for the client application?
¨ Is the REST resource using HTTP error codes and media type X-Application-error-code?
¨ Are URLs created for each resource?
¨ Are clients only receiving the representation of the resource?
¨ Can the resource integrate into other applications?
¨ Is the resource explicitly using HTTP actions?
¨ Does the resource transfer XML, JavaScript Object Notation (JSON), or both?
¨ Is the resource a unique URI?
¨ Is the resource fully documented? Specs need to have a Resource section that fully describes the resource

Good and Bad Examples

Making a Phone Call

Good REST Design

GET /devices/4253819986?deviceType=phone (retrieve phone 1)

GET /devices/7865539566?deviceType=phone (retrieve phone 2)

GET /connections?deviceType=phone (retrieve a telephone connection object)

POST /connections?phone1=4253819986&phone2=7865539566&action=connect (make a call)

POST /connections?&phone2=7865539566&action=hold (place phone2 on hold)

DELETE /connections?phone1=4253819986&phone2=7865539566&action=disconnect (hang up)

Poor REST design

POST /call/4253819986 (verb used as resource not data centric, no resource created for POST)

POST /send (verb used as resource to call SOAP operation, no resource created for POST)

POST /createCall (verb used to call a server component, no resource created for POST)

PUT /communications/audio/connect (extraneous words – “communications” and “audio” and verb use)

GET /connections?&phone2=7865539566&action=hold (improper use of GET, no retrieval)

DELETE /connections?phone1=4253819986&phone2=7865539566&action=disconnect (connections are coming from a pool, so the resource is not deleted)

Good REST Design

GET /drugs

GET /drugs/389834

GET /drugs/389834/interactions

GET /profiles/58914/drugs/389834/prescriptions

PUT /profiles/48934/drugs/389834/prescriptions/4893/dosages/41

Poor REST Design

GET /medicine

GET /medicine/pharmacy

GET /medicine/companysuggested/interactions

GET /patient/profile/medicine /389834/prescriptions

PUT /profiles/48934/drugs/389834/prescriptions/4893/dosages/41?profileType=employee