Peter Robinett

API v2

In the interest of simplicity and clarity a new version of the API is now available. This API v2, or version 2, is constructed upon REST principles and should be easier to use. It is available in anyMeta 4.18 and later versions.
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: 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: 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:,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 In addition to the methods seen before, you can also get incoming edges: GET and outgoing ones: GET This can be further qualified with a specific predicate: GET As mentioned earlier, you can append a list of additional fields you would like in your response: GET,props Likewise you can get other “identities” (identifiers) of a Thing. Here are mine: GET 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 GET Creating To create a Thing you make a request to the thing root. For example: POST 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: [{"raw": "urn:rfid:2E647A8A", "type": "rfid"}] Or a new Edge: POST body: [{"object_id": “444”, "predicate": "INTEREST"}] If you specify the predicate in your URL then it isn't needed in the request body: POST 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 body: {"kind": "PERSON", "text": {"title": "Peter – The Best – Robinett"}} Or one of its Edges: PUT 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'.