API v2

The traditional API is very powerful, but it has sometimes been too complicated or 'heavy' for simple uses. Hopefully thanks to this guide the traditional API is now more accessible for you. However, while the traditional API is still present and is the one used by the existing anyMeta libraries, it may be wise to use the new API if you are starting a new project where you cannot use an existing library. The new API uses JSON across the board and the same OAuth authentication used in the traditional API is required when appropriate. Expressive, Composable URLs The new API is has simple, expressive URLs for API methods. This makes it easier to construct requests and to understand them at a glance. The URLs follow the following pattern: anymeta_site/api/api_version/thing/entifier/qualifier(s)?parameters=comma,separated What does this mean? It's probably easiest to look at an example and take it apart: http://www.mediamatic.net/api/v2/thing/46538 As you can see we have a URL referring to a Thing, specifically the Mediamatic Bank Thing. Let's break the URL down: anymeta_site: http://www.mediamatic.net api_version: v2 identifier: 46538 As you can see, we're getting information about Thing 46538 using v2 of the API. And if you've entered the address in your web browser, you've already discovered one of the key benefits of the v2 API: we finally have a simple method to get a Thing! You'll also notice that there isn't a lot of information about the Thing included in the response. This is by design in order to accommodate common use-cases, such . You can get additional information by adding the fields query parameter. You can give a comma separated list of fields. For example: http://www.mediamatic.net/api/v2/thing/46538?fields=axo,props The API version in the URL is an important addition, as it means that anyMeta and its API methods can evolve without running the risk of breaking existing API clients. Of course, this is also means that you need to update your requests when you want to use a new or updated method. REST Interface Remember how we mentioned that you could view the earlier example URL in the browser? This is thanks to the fact that API v2 not only accept POST requests but also other types. Inspired by REST it uses four HTTP verbs to indicate the desired operation on a resource: GET: Get something, such as a Thing or an Edge. This means you can now test requests by simply visiting the request URL in your web browser. POST: Create a new resource. If you are creating a new Thing you should not include an identifier, while if you are creating an Edge or similar in reference to a Thing then the Thing's identifier is needed. PUT: Update something in place. DELETE: Delete the specified representation. Reading To get an object you would make a request like: GET http://www.mediamatic.net/api/v2/thing/49557 In addition to the methods seen before, you can also get incoming edges: GET http://www.mediamatic.net/api/v2/thing/46538/incoming and outgoing ones: GET http://www.mediamatic.net/api/v2/thing/46538/outgoing This can be further qualified with a specific predicate: GET http://www.mediamatic.net/api/v2/thing/46538/incoming/presented_at As mentioned earlier, you can append a list of additional fields you would like in your response: GET http://www.mediamatic.net/api/v2/thing/49557?fields=axo,props Likewise you can get other “identities” (identifiers) of a Thing. Here are mine: GET http://www.mediamatic.net/api/v2/thing/49557/entities In addition to the Thing IDs we've been using in our examples we can also use email addresses (notice the '') or RFID identifiers: GET http://www.mediamatic.net/api/v2/thing/mailto:peter@bubblefoundry.com GET http://www.mediamatic.net/api/v2/thing/urn:rfid:2E647A8A Creating To create a Thing you make a request to the thing root. For example: POST http://www.mediamatic.net/api/v2/thing/ body: {"kind": "PERSON", "text": {"title": "Peter Robinett"}} The response will include information about the newly created Thing, if you had sufficient permissions to create it. As you saw with requests to read data, requests to create data build upon the logical URL pattern: To create a new identity for a Thing: POST: http://www.mediamatic.net/api/v2/thing/49557 [{"raw": "urn:rfid:2E647A8A", "type": "rfid"}] Or a new Edge: POST http://www.mediamatic.net/api/v2/thing/49557/outgoing body: [{"object_id": “444”, "predicate": "INTEREST"}] If you specify the predicate in your URL then it isn't needed in the request body: POST http://www.mediamatic.net/api/v2/thing/49557/outgoing/interest body: [{"object_id": “444”}] Updating The update methods will return the same data as their GET counterparts but first modify the representation based upon the data provided in the request body. You can update a Thing: PUT http://www.mediamatic.net/api/v2/thing/49557 body: {"kind": "PERSON", "text": {"title": "Peter – The Best – Robinett"}} Or one of its Edges: PUT http://www.mediamatic.net/api/v2/thing/49557/outgoing body: [{"edg_id": “134124”, "predicate": "INTEREST"}] Notice here that since our URL does not specify a specific edge we can instead update many edges at once and so must pass a JSON Array of edge changes in our body. Deleting This version of the API does not support deleting Things or Edges yet. If you need to do this then you will have to use the traditional API. JSONP You can add the query parameter jsonp_callback to any request to give the Javascript function that should be called in the body of the JSONP response. If you are using jQuery's ajax() method you will need to set the jsonpCallback setting to 'jsonp_callback' instead of 'callback'.