Page History

...

For our purposes, application state refers to what the client is currently seeing with regard to the resource accessed by a URI. An important part of application state is not simply what static content is available to the client at a given time, but also what links are available that inform the client of choices that can be made. These links enable the client to change the state of the application (i.e., when I link is activated, the client will receive new static and hypermedia content, thus changing the state of the client). Again, typical website visitors engage in this activity all the time. The relevant question is, how does the server know what content to return? More importantly, how does the server know what links to return?the resource content as it exists in the client at a specific point in time. As we have noted above when describing hypermedia, web servers (and web APIs) return digital content, but this content can be separated into two categories: static and hypermedia. Static data is what a client considers meaningful and directly related to the URI itself (e.g., GET /orders/1234 is expected to return information related to order #1234, such as customer number, order date date, line item detail, etc.). Hypermedia data, however, informs the client what new states are available. For instance, our order resource might also include the following hypermedia:

• A link to the related customer resource.
• A link to each related item on the order.
• A link to the shipping vendor's packing tracking information.
• A link that allows the visitor to cancel the order.
• A link that allows the visitor to see all open orders.

Each of these links are capable of changing the application state (i.e., the resource content as it exists in the client at a specific point in time). Note, however, that some of these links simply request additional resource content (i.e., via the GET method) but links are also used to make changes to the resource state (such as cancelling the order). The important point is that all of these links were provided by the server at the time the resource was requested. This implies that the server used the resource state (i.e., the resource content as it exists in the server at a specific point in time) to determine which application state links were applicable when the request was made.

This describes a type of functional contract. Servers inform clients what can be done using hypermedia and clients inform servers what they want to do using this hypermedia. This is where a stateless design of our RESTful APIs becomes possible. Servers are not tracking the application state of each and every client. Servers don't care what the application state of each and every client. Servers, i.e., our APIs in this context, only care about what clients request at the time the request is made. Our APIs then package up the resource content (static and hypermedia) as appropriate at the time. Clients, on the other hand, are likewise not supposed to care about the resource state of the server. They are only concerned with the application state and any responses the server returns when a change in the resource state is made.

Let's revisit the GET /orders/1234 API again. It was previously suggested that the resource might include a link to cancel the order. In order for HATEOAS to work as intended, the server needed to verify that order #1234 was capable of being cancelled at that time. This could rely on a number of factors, such as permissions of the user, whether the product was already shipped, or terms and conditions of this order. In any case, the server makes a determination and returns or withhold the link (hypermedia) that informs the client that this order may be cancelled. Furthermore, the client must use this link to request a state change (i.e., cancel the order)In many data systems, clients and servers share state (i.e, the system is stateful). This is how traditional OpenInsight applications are designed. For instance, if a form reads a row, that row is locked and the server maintains the state of this lock so other clients are unable to modify this row. As described in the What is Rest? article, RESTful APis are supposed to be stateless. This means that once the server provides a client with a resource, it no longer cares what the client knows or what the client is doing with the resource data.