Solved: Recommended POST format - Page 2

Report Inappropriate Content · 03-16-2017 08:51 AM

When reading the excellent eBook Web API Design: The Missing Link, I stumbled upon a problem.

In the chapters "Designing Representations" and "More on Representation Design", the author argues to include a "kind" property, a "self" link and for related resources a link to those resources.
Example:

{
  "self": "https://dogtracker.com/dogs/12345678",
  "id": "12345678",
  "kind": "Dog"
  "name": "Lassie",
  "furColor": "brown",
  "owner": "https://dogtracker.com/persons/98765432"
}

This is pretty neat.

While this works great for GETting a resource, how should this be formatted when POSTing a resource?

The "self" doesn't make sense. But what about the "kind" and even the "id"?
Also, the "owner" should probably be indicated just with its id?

Are there any recommended practices for formatting JSON for a POST request as well?

Report Inappropriate Content

I agree that it does not make sense to include "self" in a POST that is performing a create — the server will allocate the URL for the new resource.

In my own designs, I never include an "id" property in resources. From the point of view of the API client, the value of "self" is the resource id (URI stands for uniform resource identifier). In my opinion, when you include an "id" property in a resource you are effectively leaking your implementation detail through the API — the value of "id" is probably a database table primary key.

I think it is much better for the value of "owner" in a POST to be the URL of the owner. Later in the book, there is a discussion of how to handle the case where the owner can be either a person or an institution. If you only include an owner "id" in POST, this scenario creates a challenge — how do you indicate whether the value of "id" is the id of a person or the id of an institution? If the value of "owner" in a POST is a URL, you have no such problem. I believe it is better if every id in an API is a URI, with HTTP URLs being by far the most useful type of URI.

In general, I find that there are 3 common categories of property in the JSON representation of a resource — read-write, read-only, and write-once. In this example, "self" is read-only. "kind" is write-once. "name", "furColor" and "owner" are read-write. JSON schema can express read-only, but I'm not aware of a standard language (other than natural language) that can express write-once, even though it is very common.

View solution in original post