I'm new to hypermedia. After doing a bunch of research I'm currently investigating exposing an API as a set of processes/workflows as opposed to entities. Of course I'll still need entities, but it seems reasonable to assume that a client is looking to invoke actions in order to achieve a goal so exposing a set of processes for each goal sounds like a good idea.
The sample API/service we've been using is an issue tracker service. The processes I'm thinking of exposing are:
1. Create an issue.
2. Close an issue.
3. Update an issue.
4. Browse issues.
Let me try to cut to the chase so that this is not too long of a read. If you already have an issue ID then I can expose a link for closing it. However, most likely you'll want to search for the issue you're looking to close. If I know you're coming from the 'Close an issue' process and you ask for the collection of issues, can I have the action to close the issue in the collection instead of repeating it in each embedded item? I'm thinking of doing this so the payload is smaller. For example, below is what I'm thinking would be the representation for the collection:
{
"count" : 10,
"_links" :
{
"curies" : [{"name" : "itrel", "href" : "
http://localhost/issuetracker/docs/rels/{rel}", "templated" : true}],
"itrel:closebyid" : {"href" : "http://localhost/issuetracker/issuestoclose"}, "next" : {"href" : "
http://localhost/issuetracker/issues?close&offset=5{&count}", "templated" : true}
},
"embedded" :
{
"itrel:issue" :
[
{
"title" : "first bug",
"description" : "description of first bug.",
"id" : 1,
"_links" : {"self" : "
http://localhost/issuetracker/issues/1"}
},
{
"title" : "second bug",
"description" : "description of second bug.",
"id" : 2,
"_links" : {"self" : "
http://localhost/issuetracker/issues/2"}
},
{
"title" : "third bug",
"description" : "description of third bug.",
"id" : 3,
"_links" : {"self" : "
http://localhost/issuetracker/issues/3"}
},
{
"title" : "fourth bug",
"description" : "description of fourth bug.",
"id" : 4,
"_links" : {"self" : "
http://localhost/issuetracker/issues/4"}
}
]
}
}
The goal is to be able to navigate to the "itrel:closebyid" link. This link needs an item id. Is it ok to have the client get the id from the embedded resource and us it in the link of the representation?
Thanks,
Nick