REST API - how does the client know what a valid payload is to POST to the resource?

Question

One of the goals of the REST API architecture is decoupling of the client and the server.

One of the questions I have run across in planning a REST API is: "how does the client know what is a valid payload for POST methods?"

Somehow the API needs to communicate to the UI what a valid payload for a given resource’s POST method. Otherwise here we are back at depending on out-of-band knowledge being necessary to work with an API and we are tightly coupled again.

So I’ve had this idea that the API response for a GET on a resource would provide a specification for constructing a valid payload for the POST method on that resource. This would include field names, data type, max length, etc.

This guy has a similar idea.

What's the correct way to handle this? Are most people just relying on out-of-band information? What are people doing in the real world with this problem?

EDIT

Something I have come up with to solve this problem is illustrated in the following sequence diagram:

The client and the api service are separate. The client knows:

1. Entry point
2. How to navigate the API via the hypermedia.

Here's what happens:

1. Someone (user) requests the registration page from the client
2. The client requests the entry point from the API and receives all hypermedia links with appropriate meta data on how to traverse them legally.
3. Client constructs the registration form based on the meta data associated with the registration hypermedia POST method.
4. User fills in the form and submits.
5. Client POSTs to the API with the correct data and all is well.

No magic /meta resouces, no need to use a method for the meta data. Everything is provided by the API.

Thoughts?

Eaton

The problem with sharing resource for GET and POST, using GET for metadata, is that you would normally use the GET to retrieve the widget you POSTed or a list of those widgets. If you're going to allow the API to 100% drive the UI, you will need some sort of endpoint that provides metadata. I just wouldn't use GET /widget. I'd use something like GET /widget/meta. However, like others have said, this couples your UI to the API's implementation of the metadata. But if you follow some specification (or create one), then you're only coupled to the spec. – Saundrasaunter

Answer 1

Most people are relying on out-of-band information. This is usually ok, though, because most clients aren't being built dynamically, but statically. They rely on known parts of the API rather than being HATEOAS-driven.

If you are developing or want to support a metadata-driven client, then yes, you're going to need to come up with a schema for providing that information. The implementation you linked to seems reasonable after a quick skim. Note that you've only moved the problem, though. Clients still need to know how to interpret the information in the metadata responses.

Cephalalgia

What do they need to know to interpret it? The valid response is fully defined. – Eaton

They are now tightly coupled with your metadata endpoint and the response it gives. – Linsang

@troylshields The metadata endpoint IS the endpoint. The client should adapt to the response. Just like http builds a page based on the response. – Eaton

Well I agree with @eric-stein that you've just moved the problem. Clients aren't being built dynamically and the only piece that should be tightly coupled to the REST service is one interface that can be easily swapped out. – Linsang

@Eaton In HTTP, the server and client share out-of-band information - the HTTP spec. <b> means bold, etc. Your client and server will need to share out-of-band information on what to do with the contents of your metadata. That's all I'm saying. – Cephalalgia

Answer 2

Your are right, the client should understand the semantics of the links in the response, and choose the right one from them to achieve its goal. The client is coupled to the semantics the API provides about this and not to the API itself. So for example a client should not retrieve information from the URI structure, since it is tightly coupled to the actual API.

I know of 2 current solution types about this:

• by HAL+JSON you use IANA link relations to describe what the link does, and vendor specific MIME types to describe the schema of the fields
• by JSON-LD (or any other RDF format) with Hydra vocab you send back RDF metadata according to the operation the link calls. This meta-data can contain the validation details of the fields (xsd vocab) and the semantics of the fields (microdata, microformats, etc...). This information is completely decoupled from the API implementation, so it might be a better option than using vendor specific MIME types, but Hydra is still under development and HAL is much simpler.

However your solution is valid as well, I think you should check both of these, since they are already standard solutions, and the uniform interface / self-descripting message constraint of REST encourages the usage of existing standards instead of custom solutions. But it is up to you if you want to create an own standard.

Wade

Answer 3

I think you are asking about, Rest API meta data handling. Unlike SOAP, Rest APIs doesn't use meta data normally, but sometimes it can be pretty useful, once your api size gets bigger.

I think you should look into swagger. It is the most elegant you can find out for rest apis. I have being using it for sometime and with the annotation support it is being rather easy to work with. It also has many examples found on github. Other advantage is, it contains nice configurable ui.

Apart from that you can find other ways of doing it like WADL and WSDL 2.0. Even-though I haven't being using them, you can read more about them here.

Callant

That's pretty much exactly what I was saying a REST API shouldn't do. It shouldn't need to publish it's API meta data in some WSDL or other format because at that point your client and server are tightly coupled. The API should provide all necessary information for interaction with it at the time of interaction. – Eaton

Answer 4

With RFC 6861, you can link to your form with create-form and edit-form Link Relations, instead of the client constructing the form by itself. The corresponding form should have the necessary schema to construct the POST request.

Morissa