RE: How to shape a Hydra endpoint for this style of API

Hi Adam,

On Tuesday, January 12, 2016 3:40 PM, Adam Christie wrote:
> I am looking at how to construct a Hydra endpoint for an API that is
> currently under development.

Cool, could you share some more details of what you are building?


> The API is organised in a hierarchy consisting of:
> 
> /{customer}/{section}/{id}
> 
> where {customer} and {section} could both be strings or numbers and
> {id} is a string.
> 
> There are actions available at each level of the hierarchy, e.g.
> - a POST operation to /{customer} may result in a new 'section'
>   being created (provided the auth passes)
> - a GET operation to /{customer}/{section} retrieves stats and
>   information about that customer section
> - a DELETE operation sent to /{customer}/{section}/{id} results
>   in the removal of a particular entity within that customer's
>   section
> 
> So as you might imagine, there can be different entity types at each
> IRI and can vary based on HTTP verb, for both what an operation
> expects and what it returns.
> 
> I would like to understand how best to represent this API style in
> Hydra.

Have you seen the event demo API?

  http://bit.ly/hydra-console-event-api


> Having read through the spec and the Events API example, I can
> see that IRI templates may perform a role in this representation, but
> I'm not clear as to exactly how.

It really depends on what exactly you wanna achieve. There's nothing that
inherently requires IRI templates in what you describe.


> Will a separate vocabulary document be needed at each endpoint, e.g.
> /{customer}/doc or /{customer}/{section}/doc ?

No, a single vocabulary will work as well.


> Can a particular IRI accept more than one type of class in this
> scheme?

By "accept" I assume you mean the payload of a POST or PUT. Sure.


> Would I have to differentiate between endpoints as to what
> entity they were expecting?

You can define operations that apply to all instances of a specific class or
targets of a specific property (look for supportedOperation at [1]) or you
simply assign operations to resources (endpoints) directly (example 6 [2]).


> I'd be most grateful for any examples where people have done something
> similar and also any wisdom that you can pass on.

It's difficult to answer your questions as they are quite abstract. The more
concrete the questions are the more helpful the answers will be. Don't
hesitate to share some concrete examples. It's easier that way to point out
mistakes or provide suggestions.

Could you please also join the Hydra W3C Community Group. The steps to do so
are described at 

  http://www.hydra-cg.com/#community


Thanks,
Markus


[1] http://www.hydra-cg.com/spec/latest/core/#documenting-a-web-api
[2]
http://www.hydra-cg.com/spec/latest/core/#adding-affordances-to-representati
ons


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 13 January 2016 22:00:43 UTC