How much should be specified for clients calling a REST service?

Question

I'm trying to better understand the pros and cons of REST. I think I have a pretty good hold on the core factors, particularly creating endpoints/URIs that better represent the resources in play and using hypermedia to eliminate coupling of clients and the URIs to the application

My understanding is that if clients are interacting with the REST application properly, they are always accessing the base endpoint and using the hypermedia returned to direct them to the resources they want to interact with. Some knowledge of what will be returned is required though, since the specifics of the hypermedia used or what the relationships returned mean. A calling application needs to know, for example, that it was want to go to the "create" URI and do a PUT there to add a resource.

This seems reasonable enough, though, since the URI returned with the "create" relationship can change at the discretion of the server and the client will still be able to add the resource. However, what happens when that resource required a considerable amount of metadata? How does the client know what data is required and how to provide it? Does this all need to be provided to the client separately? It seems like it must have to be, the client can't magically know that information.

If that is the case, however, it seems that the primary thing we're getting from REST is that URI independence. Something that, though certainly valuable for some applications seems like it's probably not worth the overhead required for both applications in most contexts. Am I missing something here? What level of documentation and knowledge-sharing is expected to be shared with the client before they can call the service?

It occurs to me in part that I may just need to see an service I know is truly RESTful and learn from how that is architected. Are there any great public examples of a RESTful service that I could look at to help better understand this?

Answer 1

I'm assuming that we are on the client side and the server side implements (at least) a Level 3 API in the Richardson maturity model

So, my answers to How much should be specified for clients calling a REST service is as much as needed and possible.

Ok, that's naive to say. However, as in any other application, during the design phase, we could have to deal with issues like

• Limited resources
• Limited budget
• Limited knowledge
• Deadlines
• Functional and non-functional requirements

The design should consider seriously the issues above mentioned because is during the API design when it's decided how autonomous will the clients allowed to be.

However, what happens when that resource required a considerable amount of metadata? How does the client know what data is required and how to provide it? Does this all need to be provided to the client separately? It seems like it must have to be, the client can't magically know that information.

Here, you have introduced requirements, so you are almost answering yourself. How to make it possible is "implementation details".

Some mechanisms for providing such details are:

• Links to schemas and documentation
• Informing methods and formats alongside the Links
• Using the headers diversity for communicating metadata and behaviours

Nevertheless, some documentation is still necessary. There're more things related to the API usage. For instance:

• Security
• Catalogue of errors
• Snippets

As you may guess, designing and implementing rich REST APIs could be difficult and costly. But there're many frameworks and tools that make it easier. They allow you to focus on the business rather than on the implementation details.

Finally, to the question

Are there any great public examples of a RESTful service that I could look at to help better understand this

Yes, but how you may guess (again), each provider will have designed and implemented the API accordingly with its understanding of the REST and all those things I have mentioned at the beginning of the answer.

Googling by Good Examples of Hypermedia APIs, I have found the follow link:

• Api Evangelist. It's a bit old post, but the APIs mentioned are still alive and they seem to me a good example of what an API could be.

  • FamilySearch`: API Doc. For example, check out the Person resource. Follow with the Links attribute. There's a lot of information related to the how to interact with the resource referenced by the URI. They also have SDKs where you could see the client implementation if you are interested.

  • Foxycart API. This one is a little bit less self-documented than the previous one, so you can imagine that the client will have to hard code some information. For instance, which method and data formats to use every time the client calls the service. Look at the Link model. It provides neither the allowed methods nor the supported formats.

  • PayPal. Check out Invoice API. If I didn't miss any detail, this API seems to be somewhere in between the two previous examples. It provides more metadata than Foxycart but less than FamilySearch.

---

Despite recommending books is off-topic here, If you are interested in REST API designs, it may interest you REST API Design Rulebook. The author purposes a model language (WRML) for designing APIs. I have learnt a lot about REST and API design reading the book. But, if you read it, do it with discretion. What the author call rules may or may not be standard rules. Leave a window open for improvement. Keep yourself open-minded and adapt your designs to your needs and requirements. All time.

Answer 2

Some prior knowledge is required, yes, but most of it you already know. For example:

• does your client know how to make calls over HTTP(S)? If yes, then you know how to talk to any REST service exposed over HTTP(S).
• does your client understand URIs? If yes, then it knows how to identify the resources of the REST service.
• does your client understand JSON or XML? If yes, then your client knows how to parse the REST service responses.

This allows you to speak to the service. But how do you understand what it’s “saying”?

From the media type. The media type describes the data model (the resources), the relations these have, etc. This is the “language” that the clients need to speak. Without understanding the media type you don’t understand the service. All of this is documentation that your client needs to know. Any other documentation is just extra help.

Finally, hypermedia allows for a flexible API. Compared to SOAP, for example, in REST your API is more dynamic (i.e. does not have a static contract) and that allows for easier evolution of the API without breaking existing clients.

Answer 3

Oracle: when you aren't sure how to do something with REST, as how you would do it with a web site.

what happens when that resource required a considerable amount of metadata? How does the client know what data is required and how to provide it?

So, how would you do this with a web site? The user would load the base endpoint, and look around in the representation of that resource for the link they want. They would click the link, and the representation of that resource would be a form, with labels on the fields to communicate the semantic meaning. The user fills in those forms, and submits it, and that submission produces a representation of another form (you did say a lot of meta data), much like the first, and finally we get to the last form. When the user submits that, the server looks at the provided data and changes its own state.

Note that there is a separation here: the media type (HTML) communicates links and forms to the client, which knows how to parse and present them. The semantics of those links and forms are embded in the HTML representation, and target the user.

In a machine API, the basic design is the same; the machine needs to understand the protocol (which link to follow, how to work through multiple forms, and so on), and needs to understand the semantics (how to map the information in the representation to some common understanding). This is usually done out of band (link relations that are defined by common schemas).

To manage extensibility, you ensure that the server provides defaults (so that existing clients can ignore new fields that they don't understand), and you ensure that the clients don't insist on specific fields (so that the server can re-order or remove a semantic).

A calling application needs to know, for example, that it was want to go to the "create" URI and do a PUT there to add a resource.

Now, to be fair, "PUT" isn't so well understood, because it's not supported in HTML. To understand PUT semantics, one needs to be thinking in terms of the original use case, which was remote publishing.

The basic game is the same: hypermedia links that lead the client to the right location. The client can use OPTIONS to establish that remote editing is supported. Thus the client can load the representation, make changes to it, and PUT it to the location it loaded it from.

Within the representation of the resource itself, the game is much the same as before: the client and server need to agree upon the media type, and the client needs to understand the insert, delete, and modify mechanisms of that type, and the common semantic cues used.

Many of the constraints you'll want to have in your representation will be similar to the constraints you want in versioned messaging. Greg Young's eBook may help with that.

Answer 4

Yes, RESTful APIs and services (if written well) can be self documenting to a point. However there still needs to be a fair amount of documentation to understand the different HTTP verbs to use as well as the payloads in and out of the services to be able to fully use the API. One example is Twitter. You will see that even though their service is structured around resources they still have a fair amount of documentation about their public API.