API
From Colourphon
Contents |
URL Structure
Apache modrewrite simply redirects the request to index.php - borrowing a trick from wordpress .htaccess file. Note I like this solution because it means there is no complex maintenance of multiple rewrite rules for ever and ever hereafter. It does mean that we need to be certain to serve a proper 404 when necessary, but as we are serving status codes, this can only be a good thing.
# Begin Colourphon rules
# if the file does not exist and the url is not a directory, then redirect the request to index.php
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
# End colourphon rules
Some example URLs
- Here we are always requesting version 1, and that will probably remain the case unless we do something VERY drastic and breaking. We are also just requesting an index, this would default to html output.
- here we are sending an isbn to colourphon and we'll be getting rdf output (when we've written the rdf! :) )
- Here we are searching for something - and by not specifying output we'll get html (when we've implemented the search :) )
- modrewrite simply redirects the request to /index.php:
- * colourphon.co.uk/ {VERSION} / {DO} [/ {WHAT}] ? [ {WITH} isbn|query|identifier ] [ {OUTPUT} rdf|html|json ]
Note: submit type queries
Submit type queries will always check to see if we have already processed that URL and will return a set of data either from the store if already exists or from the submission itself.
submit a url
submit a url of an image to colourscan. method: post
action: api.colourphon.co.uk/v1/submit/url
parameters:
url=http://some.url/to/image.jpg
examples:
http://api.colourphon.co.uk/v1/submit/url?url=http://some.url/to/image.jpg
body: representation of analyzed data in whatever format was chosen
Responses:
- Resource has been created
- 201
- Resource has been accepted but not processed
- 202
- Resource already exists
- 302? or 303?
- bad request
- 400
- failed or otherwise can't give you anything
- 404
submit isbn
method: post
action: api.colourphon.co.uk/submit/
parameters:
isbn=<isbn>
identifier=<a product identifier>?
examples:
http://api.colourphon.co.uk/submit.php?isbn=0124567X with mod-rewrite: http://api.colourphon.co.uk/submit/isbn/0124567X
Response:
success
http status response: 201
mime type: text/plain
body: url to processed image record
already exists
http status response: 302? or 303?
body: url to existing image record
bad request
http status response: 400
failed
http status response: 404
