The new Vesica RESTful API is now available in beta. This page explains how to use the REST service and provides a sample template to retrieve data from your Vesica account. Until this service runs in beta through June / July 2013, only the GET method is available via the API. POST, PUT and DELETE methods will become available once the API moves out of beta.
The old XML driven API is still available, but is deprecated and will be phased out at the end of this year.
Each request to the Vesica REST server expects at least a resource and if you are after a specific item, it also expects a resource ID. The following information should help clarify how the API can be used:
- URL: api.vesica.ws
- Resources Supported: collections, pieces
- Required Parameters: user_api_key, account_api_key
- Optional Parameters: limit (int) (max 100), offset (int)
- Methods: GET (PUT, POST and DELETE coming soon)
- Input Formats Accepted: Simple data array of parameters OR a JSON encoded object
- Output Format: JSON encoded object with 3 properties:
- code - this is the http status code, e.g. 200, 201, 501 etc
- status - the corresponding http status for the above code
- data - the data you requested or an explanation of the error code and status
api.vesica.ws/collections to see all the collections in your account and a summary of pieces in those collections.
api.vesica.ws/collections/45 to see collection 45 and a summary of the pieces in that collection.
api.vesica.ws/pieces to see a summary all the pieces in your account (default 25, maximum 100 at a time).
api.vesica.ws/pieces/2867 to see all details of piece number 2867. Note that 2867 is the piece's system ID, not accession number.
Things to keep in mind
- Even when piece / object data is returned in summary format for the collections/xx and pieces calls, you will see ALL properties of the object / piece returned, except they will be blank. This is temporary whilst we run the API in beta mode, but rest assured you will see all the data when you call the API for one pice.
- Whilst it is highly unlikely that we will take away or rename any of the elements returned (this might happen as we are still in beta, but unlikely nonetheless), we will almost certainly be adding more. If any elements are removed, this page will be updated accordingly.
You can download a code sample written in PHP here. For assistance, please login to your account and create a support ticket or email .