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?

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.