Here is an example of a self-documenting REST response. Ideally every API call should let the developer append a param like help=true to get details such as calling context, documentation links, examples, and related/further calls that might be made. Of course, those additional URLs also include the help=true to ensure hypertext-powered API browser surfing is possible (Further calls might also be part of the response in some cases, following the HATEOAS model.)
[javascript]
{
type: ‘post’,
id: 123,
title: ‘How to make pancakes’,
…
# other normal response stuff
…
# some calling context help
caller: {
type: ‘user’,
id: 789,
name: ‘happyjoy’,
role: ‘member’
},
# general docs link
docs: ‘https://example.com/docs/posts#get’,
# usage examples for this particular resource
examples: [
{
url: ‘https://example.com/posts/123?help=true’,
explanation: ‘get post 123’
}
{
url: ‘https://example.com/posts/123?metadata=true?help=true’,
explanation: ‘get only metadata for post 123 (omits the description)’
}
],
# calls related to this particular resource
related: [
{
comments: [
{
url: ‘https://example.com/posts/123/comments?help=true’,
explanation: ‘get comments for this post’
}
],
owner: [
{
url: ‘https://example.com/users/5555?help=true’,
explanation: ‘get author details’
}
]
editor: [
{
url: ‘https://example.com/users/8888?help=true’,
explanation: ‘get editor details’
}
]
}
]
}
[/javascript]
