Writing the Review 31 API
Mon 13th Jan 2014
In order to create a mobile app for Review 31, we need an API to allow the application to communicate with the site and pull data from it. There is no user interaction to speak of at Review31: comments are allowed if you sign up but have never really been used and will probably be phased out in the next major revision (Facebook comments are proving more popular, unsurprisingly).
I used the O'Reilly book RESTful Web APIs (see here: http://restfulwebapis.com ) as the basis of my design. It's great book on APIs and how best to structure them and I recommend it to anyone else who's looking to do this sort of work, although I know I haven't fully understood its workings so there are likely to be some updates later.
The site is primarily a book review site, but there are no scores given, it is just a text review. Aside from reviews, there are also essays and interviews. All three types of article are close to a normal blog post in terms of data and fields. I elected to only allow for searching through items and not provide other parts of the site on the API.
I created a profile for the site's returned fields using the ALPS profile system outlined in the book, found here: http://alps.io. This presented one of my first problems. On page 177 of the book we get an example of integrating existing Schema.Org definitions into your own definition, reusing existing definitions, and thus applying a layer of structure to your site that can help someone familiar with Schema.Org sites to quickly understand the data you are returning. Unfortunately, I found it impossible to see how to have two authors in my piece, one for the book and one for the review, since I couldn't see how to alias the sections, and secondly, the 'author' field, as described in Schema.Org is actually a generic person object. So my ALPS schema is something of a compromise:
http://review31.co.uk/Review31.xml
I will be submitting it to ALPS just as soon as I have understood how Github works so I can clone the necessary repository. After that I will change my links to point to the ALPS version.
Once the profile was done I stuck with the Content-Type: application/vnd.collection+JSON that was first shown in the book for my code. Again, the nature of the site, and the fact that my only HTTP requests will be GETs, made it the best choice from the options presented. Details of the Collection form of JSON can be found here: http://amundsen.com/media-types/collection/
I think that even with my slightly shaky profile, it should be possible for any developer to use the API as it stands, without documentation, although I will be supplying that later, when I officially link it from the site. Here is the current version for those interested:
I used the O'Reilly book RESTful Web APIs (see here: http://restfulwebapis.com ) as the basis of my design. It's great book on APIs and how best to structure them and I recommend it to anyone else who's looking to do this sort of work, although I know I haven't fully understood its workings so there are likely to be some updates later.
The site is primarily a book review site, but there are no scores given, it is just a text review. Aside from reviews, there are also essays and interviews. All three types of article are close to a normal blog post in terms of data and fields. I elected to only allow for searching through items and not provide other parts of the site on the API.
I created a profile for the site's returned fields using the ALPS profile system outlined in the book, found here: http://alps.io. This presented one of my first problems. On page 177 of the book we get an example of integrating existing Schema.Org definitions into your own definition, reusing existing definitions, and thus applying a layer of structure to your site that can help someone familiar with Schema.Org sites to quickly understand the data you are returning. Unfortunately, I found it impossible to see how to have two authors in my piece, one for the book and one for the review, since I couldn't see how to alias the sections, and secondly, the 'author' field, as described in Schema.Org is actually a generic person object. So my ALPS schema is something of a compromise:
http://review31.co.uk/Review31.xml
I will be submitting it to ALPS just as soon as I have understood how Github works so I can clone the necessary repository. After that I will change my links to point to the ALPS version.
Once the profile was done I stuck with the Content-Type: application/vnd.collection+JSON that was first shown in the book for my code. Again, the nature of the site, and the fact that my only HTTP requests will be GETs, made it the best choice from the options presented. Details of the Collection form of JSON can be found here: http://amundsen.com/media-types/collection/
I think that even with my slightly shaky profile, it should be possible for any developer to use the API as it stands, without documentation, although I will be supplying that later, when I officially link it from the site. Here is the current version for those interested: