Re: Prototype JSON-LD/Hydra wrapper for BreweryDB API

Hi Markus

On 29 Dec 2014, at 18:05, "Markus Lanthaler" <markus.lanthaler@gmx.net> wrote:

> Hi John,
> 
> On Sunday, December 28, 2014 12:51 PM, John Walker wrote:
>> Hi All, 
>> 
>> In my spare time I've been working on a JSON-LD wrapper for BreweryDB
>> and have reached what I consider to be a demo-able state.
> 
> Cool, thanks for sharing it.
> 
> 
>> Basically I have a pretty simple (and hacky) PHP script that
>> manipulates the JSON repsonses from the BrewerDB API into JSON-LD.  It
>> doesn't provide full coveage of the API yet and needs a bit of
>> tidying, I've put it in a Gist if anyone cares to take a look [2]
>> (bear in mind this is the first thing I've done in PHP).  Curently it
>> only works fully with the beer endpoints [3] from the original API.
> 
> Since you manipulate the responsens anyway, I would suggest to get rid of those top-level status and message properties (at least in case of success). The HTTP status code (200) should be enough to k now that everything went fine.
> 

Actually was considering to ditch the top-level object totally on the 'item' resources and get rid of the #id suffix on the item URIs. Granted that makes the beer (or whatever) an information resource, but in practice is there any real need to distinguish the beer from the document about the beer? In any case this resource is not an actual physical beer, but more an abstract description/specification of a certain variety of beer so could be thought of as an information resource. Plus it simplifies things.

Also wondering if it makes sense to strip out all the embedded resources/objects. For example the beer has the style object embedded with a category object in that. Instead just include a link to the style. I can see that denormalizing like this can make life easier as can get away with fewer requests in some cases, but keeping things nice and normalised just feels right to me. Ok maybe client needs to make a few more requests, but should also improve cacheability of resources and dissemination of changes. Any best practices for this in APIs?

Similarly the /beers resource might just give links to the beer resources (perhaps with the name of the beer) rather than embedding the entire description.

> 
>> I'm trying to figure out how to handle all the variations in the JSON
>> structure without using a load of repetition, nested if-then-else and
>> foreach loops, so if anyone with some PHP knowhow can suggest a better
>> method, I'm all ears.
> 
> You could either try to use templates instead of hand-coding this or replace most of the if (array_key_exists("XX",$item)) blocks with a loop and some simple configuration (an associative array should suffice).

Ok will try out these options. Probably need to dive into the details of the various end points in the original API docs to see what would be best approach.

> 
>> Also would like to know how I can get rid of index.php out of the following
>> URIs.
> 
> If you are using Apache and have mod_rewrite enabled, the following lines in a .htaccess file should do the trick
> 
>  <IfModule mod_rewrite.c>
>    RewriteEngine On
> 
>    # Serve existing files as before
>    RewriteCond %{REQUEST_FILENAME} -f 
>    RewriteRule .? - [L] 
> 
>    # Rewrite all other queries to index.php 
>    RewriteRule ^(.*)$ /index.php/$1 [L]
>  </IfModule>
> 
> 

Ok, seems simple enough.

> 
>> Some examples: 
>> 
>> A beer: 
>> http://brewerydb.semaku.com/index.php/beer/9JFYsa 
>> 
>> A beer with it's breweries: 
>> http://brewerydb.semaku.com/index.php/beer/9JFYsa?withBreweries=Y 
>> 
>> A paginated collection of beers of 4% ABV: 
>> http://brewerydb.semaku.com/index.php/beers?abv=4 
>> 
>> These support conneg (to some extent), so you'll probably get plain old
>> JSON if you open them in your browser. 
>> If you put them into the JSON-LD playground, you should get the JSON-LD e.g.: 
>> http://json-ld.org/playground/#startTab=tab-nquads&json-ld=http%3A%2F%2Fbrewerydb.semaku.com%2Findex.php%2Fbeer%2F9JFYsa 
>> 
>> I'm also using a bit of Hydra, for example the /beers list endpoint is
>> a hydra:PagedCollection and I added the links to first, last, previous
>> and next pages.  I am also going to extend the vocabulary to use more
>> Hydra to, for example, indicate which properties are a hydra:Link  and
>> perhaps detail out some IRI templates.  However as this is just a
>> learning exercise I probably will not cover all possibilites offered
>> by the original API, but hopefully enough to convince the BrweryDB
>> guys to implement it themselves.
> 
> Please keep us posted on your progress and the problems you encounter.
> 

Will do!

> 
> Cheers,
> Markus
> 
> 
>> Comments welcome! 
>> 
>> p.s. this is using my API key right now, so might exceed my limits if
>> too many requests are made (3.5K per day I think).
>> 
>> [1] http://www.brewerydb.com/ 
>> [2] https://gist.github.com/jaw111/46209e853f83d041a6dd 
>> [3] http://www.brewerydb.com/developers/docs-endpoint/beer_index 
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
> 
> 
> 
> 

John

Received on Monday, 29 December 2014 18:55:10 UTC