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

Hi Markus,

Sorry for my late response, I was very busy the last week.

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

No major roadblocks. The spec is clear enough and exemples are helpful.

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

Ok. I'll change the URL soon. /doc is already taken by the human-readable
(Swagger-like) doc, so it will be /apidoc or /hydradoc.

> Would you mind deploying a simple demo API somewhere and keep it up to
date as you improve the framework?

Sure, I've just created it.

The API from the tutorial: https://api-platform-demo-blog-api.herokuapp.com
(as it's an Herokup free plan, it can take some time on the first request).
The AngularJS client: http://dunglas.github.io/blog-client/

There is another demo API provided with the framework (a bookstore API).
I'll deploy it on Heroku this week.

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

Looks good! I'll take a look at how making such things easy from the
developer point of view.

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

So I let it as is. Thank for your feedback.

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

Sure, when a validation error occurs, the API return the following JSON-LD
document:

{ "@context": "/contexts/ConstraintViolationList", "@type":
"ConstraintViolationList", "hydra:title": "An error occurred",
"hydra:description": "name: This value should not be blank.\n",
"violations": [ { "propertyPath": "name", "message": "This value should not
be blank." } ] }The "violations" key contains a list of errors grouped by
keys of the input JSON document. Those keys generally are generally mapped
to form inputs, so it's easier for frontend dev to display server errors
below the form field causing an error.

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

Sure! I'll do it soon.

Thanks for your feedback and amazing work on Hydra and JSON-LD. We used a
lot your HydraBundle to be sure API Platform was generating valid
JSON-LD/Hydra output. It's why there are a lot of similarities betweens
format generated by the two tools (such as the /vocab URL).

Best regards.

2015-06-22 21:11 GMT+02:00 Markus Lanthaler <markus.lanthaler@gmx.net>:

> On 21 Jun 2015 at 22:48, Ruben Verborgh wrote:
> >> I would suggest to change that to something like /apidoc.
> >
> > Maybe simply /doc? They are REST/hypermedia APIs after all, so the "API"
> > as such is not that visible; it's just resources.
>
> I don't have a strong opinion about that and am completely fine with
> whatever Kévin decides. I just wanted to raise the fact that /vocab has
> been
> overly confusing and was a mistake of mine.
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>
>
>


-- 
Kévin Dunglas
Consultant et développeur freelance

http://dunglas.fr
Twitter : @dunglas
Tél. : 06 60 91 20 20