Re: [GSOC 2017] Python-HYDRA - Phase 1 Report

Hi Chris,

I think your questions remain unanswered, is that right? Let me try to help some. See inline

On 2017-06-25 20:40, Chris Andrew wrote:
> I have a few things I would like to know more about 
> regarding Hydra and how the server should work:
> 
>  1. Are there any more uses for a Collection other than showing
>     available instances?
Not sure I interpret the question correctly, but in general Collections are a set of related resources. API's Users, User's comments, etc. And keep in mind that an integral part of collections is filtering and partitioning!

>  2. What is the right way to create a new instance, should it be a POST
>     to “/api/ClassCollection” URL or the “/api/Class/<intended_id>” URL.
This is a very common REST question and there isn't a single good answer. You should inspect your requirements and ask yourself those questions:

1. Who should be responsible for assigning the resource's identity (ID). 

If it is the server, the you would POST /api/ClassCollections. The server then assigns a new URI, such as /api/Class/<id>. The <id> could be anything from autoincrement valud from relational database, a random GUID and/or some value derived from the POSTed representation.

If it is the client, then you would PUT /api/Class/<intended_id>. Not POST.

Adding to your first question, collections are important for creating new resources too!

>  3. Is the DB Model mentioned in the report good enough, or is there any
>     other way we can create a more efficient storage system?
I've only skimmed over the model section and my gut tells me that a generic model can be troublesome. On the other hand if it works, it works ;). It's not something that Hydra itself has any opinion about. Hydra is merely a conduit through you describe the client-server interactions. 

>  4. What can be a good use case for a Hydra enabled server and how can a
>     generic client be used for it?
As with any format for describing Hypermedia APIs, the general use case is to enable API evolution through dynamic discovery of request parameters and links. Hydra's strength is in the richness of its API description. That way a generic client prevents frequent changes to the client code when the API changes.

Again, this is only true with careful modeling. After all neither Hydra nor any other format will design the API for you.

>  5. Is Markus Lanthaler's Hydra Console a good starting point for a
>     generic client application?
I think so, but pay attention to possible changes in the specification which haven't been implemented in the Console and the Issues API.

>  6. How would you define argument based Operations that are not
>     dependant on a single HydraClass in Hydra, for example, I have an
>     operation called “Join”, that will take any two instances as
>     arguments and then joins the attributes of both the instances into a
>     single new instance? How will such operations be used/called?
This again goes beyond Hydra itself and touches API modeling in general. If I understand correctly, you want to join two existing resources, say /api/res/1 and /api/res/2, and create a third one?

Keep in mind the in pure REST terms there is no such thing as operation. You are constrained to resources (HTTP) methods. As an effect there is no way to accomplish what you ask about. Here's one way I would explore:

0. Let's assume there is an /api/joiner resource. (very generic term, I know. Real use case would probably call it something more business-oriented)
1. You post the URL of the first resource to /api/joiner
1a. The response is 201 Created and includes a Location header with the URL of incomplete joining operation. Say, /api/join-in-progress/123
2. You now POST the URL of the second resource to the newly created resource
3. The joined resource would be available to GET under /api/joined-resources/123.

Here's the same in minimal HTTP requests/responses:

1. Start joining

POST /api/joiner HTTP/1.1

{
  "id": "/api/res/1"
}

HTTP/1.1 201 Created
Location: /api/join-in-progress/123

2. Add second resource

POST /api/join-in-progress/123 HTTP/1.1

{
  "id": "/api/res/2"
}

HTTP/1.1 200 OK

{
  "joined-resource": "/api/joined-resources/123"
}

3. Retrieve the result

GET /api/joined-resources/123 HTTP/1.1

The example interactions above are just a sketch and ignore some specifics of JSON-LD but should give you some inspiration.

Received on Sunday, 2 July 2017 10:36:14 UTC