REST - What exactly is meant by Uniform Interface?

Question

Wikipedia has:

Uniform interface

The uniform interface constraint is fundamental to the design of any REST service.[14] The uniform interface simplifies and decouples the architecture, which enables each part to evolve independently. The four guiding principles of this interface are:

Identification of resources

Individual resources are identified in requests, for example using URIs in web-based REST systems. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server may send data from its database as HTML, XML or JSON, none of which are the server's internal representation, and it is the same one resource regardless.

Manipulation of resources through these representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource.

Self-descriptive messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cacheability.

Hypermedia as the engine of application state (A.K.A. HATEOAS)

Clients make state transitions only through actions that are dynamically identified within hypermedia by the server (e.g., by hyperlinks within hypertext). Except for simple fixed entry points to the application, a client does not assume that any particular action is available for any particular resources beyond those described in representations previously received from the server.

I'm listening to a lecture on the subject and the lecturer has said:

"When someone comes up to our API, if you are able to get a customer object and you know there are order objects, you should be able to get the order objects with the same pattern that you got the customer objects from. These URI's are going to look like each other."

This strikes me as wrong. It's not so much about what the URI's look like or that there is consistency as it is the way in which the URI's are used (identify resources, manipulate the resources through representations, self-descriptive messages, and hateoas).

I don't think that's what Uniform Interface means at all. What exactly does it mean?

Answer 1

Using interfaces to decouple classes from the implementation of their dependencies is a pretty old concept. In REST you use the same concept to decouple the client from the implementation of the REST service. In order to define such an interface (a contract between the client and the service), you have to use standards. This is because if you want an internet size network of REST services, you have to enforce global concepts, like standards to make them understand each other.

• Identification of resources - You use the URI (IRI) standard to identify a resource. In this case, a resource is a web document.

• Manipulation of resources through these representations - You use the HTTP standard to describe communication. So for example GET means that you want to retrieve data about the URI-identified resource. You can describe an operation with an HTTP method and a URI.

• Self-descriptive messages - You use standard MIME types and (standard) RDF vocabs to make messages self-descriptive. So the client can find the data by checking the semantics, and it doesn't have to know the application-specific data structure the service uses.

• Hypermedia as the engine of application state (a.k.a. HATEOAS) - You use hyperlinks and possibly URI templates to decouple the client from the application-specific URI structure. You can annotate these hyperlinks with semantics e.g. IANA link relations, so the client will understand what they mean.

Answer 2

The Uniform Interface constraint, that any ReSTful architecture should comply with, actually means that, along with the data, server responses should also announce available actions and resources.

In chapter 5 of his dissertation, Roy Fielding (originator of the ReST architectural style) states that the aim of using uniform interfaces is to:

ease and improve global architecture and the visibility of interactions

In other words, querying resources should allow the client to request other actions and resources without knowing them in advance.

The JSON-API specs offer a good example:

{   "links": {     "self": "http://example.com/articles",     "next": "http://example.com/articles?page[offset]=2",     "last": "http://example.com/articles?page[offset]=10"   },   "data": [{     "type": "articles",     "id": "1",     "attributes": {       "title": "JSON API paints my bikeshed!"     },     "relationships": {       "author": {         "links": {           "self": "http://example.com/articles/1/relationships/author",           "related": "http://example.com/articles/1/author"         },       },       "comments": {         "links": {           "self": "http://example.com/articles/1/relationships/comments",           "related": "http://example.com/articles/1/comments"         }       }     },     "links": {       "self": "http://example.com/articles/1"     }   }] } 

Just by analysing this single response, a client knows:

1. What was queried (articles in this example)
2. How are structured articles objects (id, title, author, comments)
3. How to retrieve related objects (i.e. the author, list of comments)
4. That there are more articles (10, based on current response length and pagination links)

I Hope this helps.
For those passionate about the topic, I strongly recommend reading Roy Thomas Fielding's dissertation!