RE: API Platform: a PHP API-first web framework relying on JSON-LD, Hydra and Schema.org

Hi Kévin,

Fantastic work! Did you encounter any major roadblocks when implementing this apart from the fact that the spec could be in a better shape?

On Wednesday, June 17, 2015 3:02 PM, Kévin Dunglas wrote:
> The API supports (if I've not missed) anything almost all the current
> Hydra Core Vocabulary:
> • collections and pagination
> • errors
> • API Documentation (available at the /vocab URL of all APIs)

That's a leftover in my libraries from the initial design explorations I did. I would suggest to change that to something like /apidoc. This already confused quite a few people.

Would you mind deploying a simple demo API somewhere and keep it up to date as you improve the framework? I saw you already have a sample API in your code on GitHub. This would make it easier for people to understand what your platform is capable of doing and what it will expose. Not the least, I would be interested to try to navigate it with the HydraConsole :-)


> Hydra and JSON-LD matches what we need, here are some minor issues/comments:
> • I haven't managed to understand  how to document a different set of
> attributes for create and update operation (e.g. an attribute readable
> and writeable only in a POST but only readable in PUT). It's a little
> issue but can be annoying.

You would need to define different request classes. In other words, "expects" would need to point to different things.


> • I haven't managed how to document filters (hydra:search) in the vocab
> instead of in the collection result (to decrease responses sizes). So
> they are documented in the collection return for now.

You could move them to the API doc while keeping them discoverable by including something like

   "search": "/api-doc#book-search-template"

in the collection itself and assigning the IriTemplate the same URL in the ApiDocumentation

   {
      "@id": "/api-doc#book-search-template",
      "template": ...
    }

I think, however, that generally it is better to include such controls directly in the resource representation instead of moving them to the API documentation.


> • We extended the error format to return a json object containing a list
> for "property": "error description", it was more convenient for frontend /
> JavaScript developers (it should be perfectly valid to do that, but it
> would be nice to have a similar feature directly in the spec).

I don't really understand what you mean by that. Could you please give a quick example?


> Even if it works well with Hydra Console, I'm still not sure that the
> Hydra/JSON-LD implementation is perfect. Feedback and bug reports on
> that topic are appreciated.

I'll have a closer look once you deployed a demo API :-P

Also, we should feature that on hydra-cg.com. Could you send me a PR for

  https://github.com/HydraCG/hydra-cg.com/blob/master/index.html


Thanks again for this awesome work and please keep us posted



--
Markus Lanthaler
@markuslanthaler

Received on Sunday, 21 June 2015 17:51:25 UTC