5 Signs That Your REST API Isn't RESTful

5 Signs That Your REST API Isn't RESTful

This article is for developers who are wishing to implement a RESTful HTTP interface in its original Fieldingian meaning, thereby solving real integration problems that can be addressed only to a lesser extent with today’s colloquial interpretation of the concept.

This article is for developers who are wishing to implement a RESTful HTTP interface in its original Fieldingian meaning, thereby solving real integration problems that can be addressed only to a lesser extent with today’s colloquial interpretation of the concept.

The author provides five criteria to help you make the distinction between an API that is RESTful based on the original meaning versus the colloquial meaning of REST.

There is no doubt that the term REST has undergone significant changes since its inception by Roy Fielding. There was some resistance to this change, most notably from Mr. Fielding in his Untangled Blog. However, all those participating in this resistance have had to acknowledge defeat by now, as the industry has moved past them. We’re using the terms REST and REST API not for its original meaning, but, ironically enough, for (basically) opposing SOAP, an arguably more complex and difficult-to-use contender for integration technology.

Nowadays, everything that communicates over HTTP and uses JSON- or XML-formatted messages or the HTTP Methods (get, post, put, delete, etc.) gets called a RESTful API.

This article is not about discussing whether the term is used correctly, whether certain projects are allowed to use the term, or to argue that the currently implemented APIs are somehow defective.

This article is for developers who are wishing to implement a RESTful HTTP interface in its original Fieldingian meaning, thereby solving real integration problems that can be addressed only to a lesser extent with today’s colloquial interpretation of the concept.

Because the currently available resources (documentation and software) are ambiguous at best, this article offers a simple list of often seen attributes which can help to keep a design on the right track or to differentiate between the original and new interpretation of REST.

1. Using the Application/JSON Media Type

One of the most often seen attributes of API designs is to use the Media Type application/JSON or sometimes application/XML. With Jersey (JAX-RS), it looks often like this:

@GET
@Produces(MediaType.APPLICATION_JSON)
public List<Product> getProducts() {
   ...
}

Using generic media types such as JSON is fundamentally not RESTful because REST requires the messages to be self-descriptive. Self-descriptiveness just means that the semantics of the data should travel with the data itself.

The difference is similar to the following two options. See which one you would prefer:

Object getProducts();

Or:

List<Product> getProducts();

The first one just says it returns an Object, in which case you have to know what actual type that object is to be able to cast and use it. The second one explicitly states that it is, in fact, a list of products.

By using generic Media Types, you are relying on the client to know what is inside that JSON message and how to interpret it. This is called implicit knowledge and is primarily responsible for brittleness, the tendency for something to break because of changes made elsewhere.

To counteract brittleness, it is best if all messages define their own Media Type, just as all Types in code define their own Class. This definition should not just include syntax but also how to interpret the message, how to follow its links, how to process its forms if there are any, how to display it on screen, and so on.

2. IDs in Representations

Often, representations returned from the server (or sent to the server) contain IDs (Identifiers) in form of numbers, similar to number typed primary keys in a database table. It looks like this:

{ "products": [
  { "id": 12,
    "type": 103,
    "name": "ACME Router D12"
  },
  { "id": 13,
    "type": 145,
    "name": "5m UTP Cable"
  },
  ...
]}

Again, taking an example from Java, which API would you prefer?

List<Long> getProducts();

Or:

List<Product> getProducts();

The first one gives you a list of Identifiers with which you can get a real Product from somewhere. The second one returns the explicit Object references that you can use to operate on those Products directly.

Using numerical IDs is not RESTful for two distinct reasons. First, it requires implicit knowledge from the client to know where and how those IDs can be used to get Products. This again increases brittleness and coupling. Second, it doesn’t use HTTP’s native identifiers (URIs) to identify resources.

The above example should look more like this to be more RESTful:

{ "products": [
  { "id": "/product/12",
    "type": "/type/103",
    "name": "ACME Router D12"
  },
  { "id": "/product/13",
    "type": "/product/145",
    "name": "5m UTP Cable"
  },
  ...
]}

It is not a big change syntactically but it relieves the client of having to know things implicitly.

3. Documentation Is Concerned With Paths and Parameters

Very often, if any documentation is released about an API, it contains a listing of the paths, parameters, fields that are present in the request or response. Some tools like Swagger or WADL are explicitly centered around these concepts. Both the specification and the documentation generated from these tools look like this:

Path: "/products"
  - GET: Get all products
Path: "/product/{id}"
  - GET: Get the product with given id
  - DELETE: Delete the product
...

See the Swagger Petstore for a complete example of this.

This is not RESTful in the original sense because it assumes that the client has to know all these Paths and Parameters, and what they mean implicitly. However, if the Representations use Links and Forms, like in the previous point, none of this information is relevant to the client, since the client then just follows wherever the Representations lead.

What the Specification and Documentation should do, however, is describe all the Media Types that are defined, much like the API Documentation of Java Code. A very minimal example would look like this:

Type: "application/vnd.acme.productlist+json"
  - Represents a paged product listing in the following JSON format:
    { "products": [
      { "self": "/product/123",
        "name": "ACME Router"
      },
      ...
      ],
      "nextPage": "/products?page=3",
      "previousPage": "/products?page=1"
    }
  - The "self" link in Products leads to the product listed
  - The global "nextPage" link, if present, leads to the next page
    of the product listing
  - Similarly, the "previousPage" to the previous (if not on first page)

It specifically does not mention where such a representation might be; it simply describes how to deal with it once received. It also doesn’t mention how to generate the Path to the next or previous pages or how to append Parameters or Path fragments, it simply provides those links already composed for the client to use. It shouldn’t matter how those links are created, and in fact, the server can decide to change such implementation details without notice.

4. URI Templates

URI Templates are URIs with placeholders in them. With the help of named substitution variables, they can be used to generate specific URIs. They look like this:

/product/{id}
/products?page={pageNumber}
/products?startIndex={startIndex}&endIndex={endIndex}
...

These are usually used in specifications or documentations to describe where resources reside and it is expected that clients know these templates and can generate the full URI of a specific resource.

This is done because these resources are not referenced form (linked to) other resources, so the client needs to somehow guess a resource’s URI manually. The problem with this approach is the same as before; this makes the clients break easily if some of the rules change or if the server decides to introduce a different resource structure.

The proper solution to these problems is to link those resources from somewhere else and hide all information about the URI structure from the client. Individual products should be linked from a product listing resource. If the product listing resource is paged, then those pages are again linked. The client does not decide to construct the link for the fifth page; rather, it clicks the nextPage links until it arrives at the desired page. Or, if there is a direct link to the fifth page, it chooses that link to go to that page directly.

There are of course cases in which following links is not enough. What if the client wishes to search for a product? It certainly isn’t feasible (although it should be possible) to follow links until the desired product is reached. These cases are not that different from simply linking the desired resources, however. The server always needs to tell the client how to construct links to follow. It may actually use URI Templates to do this as long as these are communicated in the messages themselves and not out-of-band (in the documentation, for example). A search page might look like this:

{
  "search": "/search?q={query}"
}

The Media Type for this representation has to describe how to interpret the URI Template, how to fill it out, and what the query means so that this knowledge is not implicit anymore. The client then makes the search request based on the information from the search page, not because of some hard-coded rules.

5. Version Number in the URI

A lot of vendors put the version of their API in the URI (for example, Yahoo, Google, Twitter, eBay, and others). This usually looks like:

/api/v1/products
/api/products_v1
/api/products?version=v1
...

From the perspective of the original REST style, these look very suspicious because URIs identify Resources that are supposed to represent some business-relevant concept. These might include Person, Customer, Product, Product Listing, Order, etc. If you ask a business person, “What is a Customer Version 2?” he or she will probably look at you very strangely and wonder whether she will have the opportunity to sell to new, improved customers.

There are practical advantages of URIs that don’t change with a version upgrade, like more flexibility when upgrading individual services, being able to bookmark links to resources without them ever changing, etc.

It is, of course, not the Product or Customer concept that is changing, but the Representation, the format of the message, or the features that it supports. There are multiple ways these changes can be described without violating REST. One of the easiest ones is to just version the Media Types themselves:

application/vnd.acme.product-v1+json

Or, the Media Type definition coulddefine extra parameters for the Media Type identification itself:

application/vnd.acme.product+json; version=1

Or, the Media Type could define that the content itself will somehow indicate the exact version, using the XSD identifier, a JSON field, and so on.

There are certainly more ways to do versioning without changing the URI and staying REST conform. Whatever the mechanism, though, it has to be explicitly defined by the Media Type.

Summary

There are at least two meanings of the word REST in use today:

  • The original meaning in which complex integration problems are solved with rigorous constraints on the architecture.
  • The colloquial meaning in which services publish some form of (often) JSON-based interface through HTTP.

Neither is better or worse than the other in any objective sense. However, if you explicitly want to leverage the full power of the original concept, you probably face the problem of distinguishing which kind of REST some online documentation, article, or software uses.

Thanks for reading ❤

If you liked this post, share it with all of your programming buddies!

What the difference between REST API and RESTful API?

What the difference between REST API and RESTful API?

Representational state transfer (REST) is a style of software architecture. As described in a dissertation by Roy Fielding, REST is an "architectural style" that basically exploits the existing technology and protocols of the Web. RESTful is typically used to refer to web services implementing such an architecture.

The short answer is that REST stands for Representational State Transfer. It’s an architectural pattern for creating web services. A RESTful service is one that implements that pattern.

The long answer starts with “sort of” and “it depends” and continues with more complete definitions.

Defining REST

Let’s start by defining what REST is and is not. For some, REST means a server that exchanges JSON documents with a client over HTTP. Not only is that not a complete definition, but it’s also not always true. The REST specification doesn’t require HTTP or JSON. (The spec doesn’t mention JSON or XML at all.)

The Origins of REST

Roy Fielding introduced the REST architectural pattern in a dissertation he wrote in 2000. The paper defines a means for clients and servers to exchange application data. A key feature is that the client doesn’t need to know anything about the application in advance. The link is to chapter five of his paper. While the entire dissertation describes the hows and whys of REST, that chapter defines the architectural pattern.

Fielding doesn’t mandate specific requirements. Instead, he defines REST regarding constraints and architectural elements.

REST’s Architectural Constraints

Here is a summary of the constraints.

  • Client-server – REST applications have a server that manages application data and state. The server communicates with a client that handles the user interactions. A clear separation of concerns divides the two components. This means you can update and improve them in independent tracks.
  • Stateless – servers don’t maintain any client state. Clients manage their application state. Their requests to servers contain all the information required to process them.
  • Cacheable – servers must mark their responses as cacheable or not. So, infrastructures and clients can cache them when possible to improve performance. They can dispose of non-cacheable Information, so no client uses stale data.
  • Uniform interface – this constraint is REST’s most well known feature or rule, depending on who you ask. Fielding says “The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.” REST services provide data as resources, with a consistent namespace. We’ll cover this in detail below.
  • Layered system – components in the system cannot “see” beyond their layer. So, you can easily add load-balancers and proxies to improve security or performance.

A RESTful service is more than a web server that exchanges JSON, or any other, documents. These constraints work together to create a very specific type of application.

Applying the Constraints

First, the client-server, layered systems and stateless constraints combine to form an application with solid boundaries and clear separations between concerns. Data moves from the server to the client upon request. The client displays or manipulates it. If the state changes, the client sends it back to the server for storage. Fielding specifically contrasts REST with architectures that use distributed objects to hide data from other components. In REST, the client and server share knowledge about data and state. The architecture doesn’t conceal data, it only hides implementations.

The cacheable and uniform state constraints go one step further. Application data is available to clients in a clear and consistent interface and cached when possible.

So, that’s the technical definition of REST. What does it look like in the real world?

RPC Over HTTP vs. RESTful

Often when someone says that a service “isn’t REST,” they’re looking at the URIs or how the service uses HTTP verbs. They’re referring to REST’s presentation of data as a uniform set of resources.

This distinction is sometimes framed as a difference between remote procedures calls (RPC) and REST. Imagine a web service for listing, adding, and removing, items from an e-commerce inventory.

In one version, there’s a single URL that we query with HTTP GETs or POSTs.  You interact with the service by POSTing a document, setting the contents to reflect what you want to do.

Add new items with a POST with a NewItem:

POST /inventory HTTP/1.1
 
{
    "NewItem": {
          "name": "new item",
          "price": "9.99",
          "id": "1001"
      }
}    

Query for items with a POST and an ItemRequest:

POST /inventory HTTP/1.1
 
{
    "ItemRequest": {
          "id": "1001"
      }
}

Some implementations accept a request for a new item with a get, too.

POST /inventory?id=1001 HTTP/1.1

We also change or delete items with a POST and an ItemDelete or ItemUpdate.

POST /inventory HTTP/1.1
 
{
    "ItemDelete": {
          "id": "1001"
      }
}

This isn’t REST. We’re not exchanging the state of resources. We’re calling a function with arguments that happen to be in a JSON document or URL arguments.

A RESTful service has a URI for each item in the inventory.

So, adding a new item would look like the example above.

POST /item HTTP/1.1
 
{
    "Item": {
          "name": "new item",
          "price": "9.99",
          "id": "1001"
      }
}    

But the similarities end there. Retrieving an item is always a GET:

GET /item/1001 HTTP/1.1   

Deleting is a DELETE:

DELETE /item/1001 HTTP/1.1  

Modifying an item is a PUT:

POST /inventory HTTP/1.1
 
{
    "Item": {
          "name": "new item",
          "price": "7.99",
          "id": "1001"
      }
}    

The difference is important. In REST, operations that use distinct HTTP actions. These verbs correspond directly to the activity on the data. GET, POST, PUT, DELETE and PATCH all have specific contracts. Most well-designed REST APIs also return specific HTTP codes, depending on the result of the request.

The critical point is that the URIs operate on the data, not on remote methods.

But there’s another reason why the resource model is essential.

REST vs RESTful and the Richardson Maturity Model

When you model your URIs after resources and use HTTP verbs you make your API predictable. Once developers know how you defined your resources, they can almost predict what the API looks like. Here again, the emphasis is on understanding the data, not the operations.

But even if you can’t make the API entirely predictable, you can document any REST service with hypertext. So, each item returned in the inventory app would contain links for deleting, modifying, or setting the inventory level of the resource. Fielding says that before a service is RESTful, it must provide hypertext media as part of the API.

Many sites don’t meet this requirement but are still called REST. Fact is, many sites break the rules in one way or another. So many that Leonard Richardson created a model breaks down REST into levels of compliance

We’ve already covered the source levels:

  • 0 – exporting an API over HTTP with methods called with arguments
  • 1 – Exporting resources instead of methods
  • 2 – Proper use of HTTP verbs
  • 3 – Exporting hypertext with objects that make all or part of the API discoverable.

Richardson’s model is his own, and it doesn’t map directly into Fielding’s spec. Since Fielding requires level three, he would say that most apps aren’t REST anyway.

The point is many services that we colloquially refer to as REST, technically aren’t.

REST vs RESTful: Does It Matter?

So, does the REST vs. RESTful comparison matter? Probably not. How well your architecture complies with an arbitrary standard isn’t as important with how well it suits your needs and can grow with your business.

The REST architectural pattern has many advantages. Fielding designed it for the web and, 18 years later, most of the constraints he had in mind are still with us. In 2000 we didn’t have Android or the iPhone. IE5 had 50% of the browser market share. It’s biggest rival was Firefox. But Fielding recognized what online applications needed and how web clients would evolve from HTML display engines into complete applications. The tools we use today have grown to suit REST, not the other way around.

Thank you for reading. Hope this tutorial will help you!

What is REST API? | Restful Web Service

What is REST API? | Restful Web Service

In this post "Restful Web Service", you'll learn: What is Web services, what is API, What is REST API, How REST works and Implementation of REST API

What is REST API? | Restful Web Service

A REST API defines a set of functions to process requests and responses via HTTP protocol.

REST is used in mobile application as well as in web applications.


What the difference between REST API and RESTful API?

What the difference between REST API and RESTful API?

Representational state transfer (REST) is a style of software architecture. As described in a dissertation by Roy Fielding, REST is an "architectural style" that basically exploits the existing technology and protocols of the Web. RESTful is typically used to refer to web services implementing such an architecture.

The short answer is that REST stands for Representational State Transfer. It’s an architectural pattern for creating web services. A RESTful service is one that implements that pattern.

The long answer starts with “sort of” and “it depends” and continues with more complete definitions.

Defining REST

Let’s start by defining what REST is and is not. For some, REST means a server that exchanges JSON documents with a client over HTTP. Not only is that not a complete definition, but it’s also not always true. The REST specification doesn’t require HTTP or JSON. (The spec doesn’t mention JSON or XML at all.)

The Origins of REST

Roy Fielding introduced the REST architectural pattern in a dissertation he wrote in 2000. The paper defines a means for clients and servers to exchange application data. A key feature is that the client doesn’t need to know anything about the application in advance. The link is to chapter five of his paper. While the entire dissertation describes the hows and whys of REST, that chapter defines the architectural pattern.

Fielding doesn’t mandate specific requirements. Instead, he defines REST regarding constraints and architectural elements.

REST’s Architectural Constraints

Here is a summary of the constraints.

  • Client-server – REST applications have a server that manages application data and state. The server communicates with a client that handles the user interactions. A clear separation of concerns divides the two components. This means you can update and improve them in independent tracks.
  • Stateless – servers don’t maintain any client state. Clients manage their application state. Their requests to servers contain all the information required to process them.
  • Cacheable – servers must mark their responses as cacheable or not. So, infrastructures and clients can cache them when possible to improve performance. They can dispose of non-cacheable Information, so no client uses stale data.
  • Uniform interface – this constraint is REST’s most well known feature or rule, depending on who you ask. Fielding says “The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.” REST services provide data as resources, with a consistent namespace. We’ll cover this in detail below.
  • Layered system – components in the system cannot “see” beyond their layer. So, you can easily add load-balancers and proxies to improve security or performance.

A RESTful service is more than a web server that exchanges JSON, or any other, documents. These constraints work together to create a very specific type of application.

Applying the Constraints

First, the client-server, layered systems and stateless constraints combine to form an application with solid boundaries and clear separations between concerns. Data moves from the server to the client upon request. The client displays or manipulates it. If the state changes, the client sends it back to the server for storage. Fielding specifically contrasts REST with architectures that use distributed objects to hide data from other components. In REST, the client and server share knowledge about data and state. The architecture doesn’t conceal data, it only hides implementations.

The cacheable and uniform state constraints go one step further. Application data is available to clients in a clear and consistent interface and cached when possible.

So, that’s the technical definition of REST. What does it look like in the real world?

RPC Over HTTP vs. RESTful

Often when someone says that a service “isn’t REST,” they’re looking at the URIs or how the service uses HTTP verbs. They’re referring to REST’s presentation of data as a uniform set of resources.

This distinction is sometimes framed as a difference between remote procedures calls (RPC) and REST. Imagine a web service for listing, adding, and removing, items from an e-commerce inventory.

In one version, there’s a single URL that we query with HTTP GETs or POSTs.  You interact with the service by POSTing a document, setting the contents to reflect what you want to do.

Add new items with a POST with a NewItem:

POST /inventory HTTP/1.1
 
{
    "NewItem": {
          "name": "new item",
          "price": "9.99",
          "id": "1001"
      }
}    

Query for items with a POST and an ItemRequest:

POST /inventory HTTP/1.1
 
{
    "ItemRequest": {
          "id": "1001"
      }
}

Some implementations accept a request for a new item with a get, too.

POST /inventory?id=1001 HTTP/1.1

We also change or delete items with a POST and an ItemDelete or ItemUpdate.

POST /inventory HTTP/1.1
 
{
    "ItemDelete": {
          "id": "1001"
      }
}

This isn’t REST. We’re not exchanging the state of resources. We’re calling a function with arguments that happen to be in a JSON document or URL arguments.

A RESTful service has a URI for each item in the inventory.

So, adding a new item would look like the example above.

POST /item HTTP/1.1
 
{
    "Item": {
          "name": "new item",
          "price": "9.99",
          "id": "1001"
      }
}    

But the similarities end there. Retrieving an item is always a GET:

GET /item/1001 HTTP/1.1   

Deleting is a DELETE:

DELETE /item/1001 HTTP/1.1  

Modifying an item is a PUT:

POST /inventory HTTP/1.1
 
{
    "Item": {
          "name": "new item",
          "price": "7.99",
          "id": "1001"
      }
}    

The difference is important. In REST, operations that use distinct HTTP actions. These verbs correspond directly to the activity on the data. GET, POST, PUT, DELETE and PATCH all have specific contracts. Most well-designed REST APIs also return specific HTTP codes, depending on the result of the request.

The critical point is that the URIs operate on the data, not on remote methods.

But there’s another reason why the resource model is essential.

REST vs RESTful and the Richardson Maturity Model

When you model your URIs after resources and use HTTP verbs you make your API predictable. Once developers know how you defined your resources, they can almost predict what the API looks like. Here again, the emphasis is on understanding the data, not the operations.

But even if you can’t make the API entirely predictable, you can document any REST service with hypertext. So, each item returned in the inventory app would contain links for deleting, modifying, or setting the inventory level of the resource. Fielding says that before a service is RESTful, it must provide hypertext media as part of the API.

Many sites don’t meet this requirement but are still called REST. Fact is, many sites break the rules in one way or another. So many that Leonard Richardson created a model breaks down REST into levels of compliance

We’ve already covered the source levels:

  • 0 – exporting an API over HTTP with methods called with arguments
  • 1 – Exporting resources instead of methods
  • 2 – Proper use of HTTP verbs
  • 3 – Exporting hypertext with objects that make all or part of the API discoverable.

Richardson’s model is his own, and it doesn’t map directly into Fielding’s spec. Since Fielding requires level three, he would say that most apps aren’t REST anyway.

The point is many services that we colloquially refer to as REST, technically aren’t.

REST vs RESTful: Does It Matter?

So, does the REST vs. RESTful comparison matter? Probably not. How well your architecture complies with an arbitrary standard isn’t as important with how well it suits your needs and can grow with your business.

The REST architectural pattern has many advantages. Fielding designed it for the web and, 18 years later, most of the constraints he had in mind are still with us. In 2000 we didn’t have Android or the iPhone. IE5 had 50% of the browser market share. It’s biggest rival was Firefox. But Fielding recognized what online applications needed and how web clients would evolve from HTML display engines into complete applications. The tools we use today have grown to suit REST, not the other way around.

Thank you for reading. Hope this tutorial will help you!