How to shape a Hydra endpoint for this style of API

Hi all,

I am looking at how to construct a Hydra endpoint for an API that is currently under development.

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. 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.

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

Can a particular IRI accept more than one type of class in this scheme? Would I have to differentiate between endpoints as to what entity they were expecting?

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

Kind regards,

Adam.



________________________________

CONFIDENTIALITY NOTICE: This private and confidential e-mail has been sent to you by Digirati Limited. This is a UK limited company, registration number SC235053 The information in this e-mail (which includes any files transmitted with it) is confidential and may also be legally privileged. It is intended for the addressee only. Access to this e-mail by anyone else is unauthorized. It is not to be relied upon by any person other than the addressee except with our prior written approval. If no such approval is given, we will not accept any liability (in negligence or otherwise) arising from any third party acting, or refraining from acting, on such information. Unauthorized recipients are required to maintain confidentiality. If you have received this e-mail in error please notify the originator immediately, destroy any copies and delete it from your computer system. The unauthorized use, dissemination, forwarding, printing or copying of this e-mail is prohibited.

Thank you.

Digirati Limited, Unit G 4, The Hub, 70 Pacific Quay, Glasgow G51 1EA | 31 Clerkenwell Close, London EC1R 0AU
Telephone +44 (0)845 643 4370: website: www.digirati.com