Using the REST interface
Introduction
The best and recommended way to use ApiOmat is with the generated SDKs that automatically tailor to your backend. But in case you’re using a language that we don’t yet support, you can use our REST API directly. The following tutorial will explain the basics of our REST API and give some examples of how to use it with cURL (which is pre-installed on most Linux distributions and can be downloaded for Windows from the project’s website).
Our REST API follows the guidelines of a RESTful Web Service and offers several resources and sub-resources, with which you can interact with through HTTP requests. You can create, read, update and delete resources by using the according HTTP methods (POST, GET, PUT and DELETE). Depending on the resource the available interactions might be limited.
The list of all REST resources, sub-resources and the available HTTP methods including a description of what they do is available in our ApiOmat REST API Documentation.
It’s devided into the three main path roots “customers”, “modules” and “apps”, as well as some additional resources with only a few sub-resources. These can be roughly seperated into design-time resources and runtime resources. Having access to design-time resources via REST API enables you to automate the build process of your app and integrate ApiOmat into tools like Maven or Ant.
Most of the customer sub-resources are for design-time, because that’s where ApiOmat accounts and apps can be created, the plan (pricing model) can be set, data can be copied from the Test system to the Live system for example etc. However, you might want to use activeUsers during the actual runtime of your app.
The modules sub-resources are mainly for design-time. It’s principally used for managing modules and classes (sometimes also called “meta models” or “data models”). A module is a logical unit that contains classes. There are ready-made modules for enhancing the functionality of your app (like the messaging module) or for integrating third-party services (for example Facebook or Twitter). For classes you can manage its attributes and server code.
The apps sub-resources are mainly for use during runtime. This is where you can save and load objects of the classes you previously created and manage images and files.
In the following examples we’ll go from A to Z - from creating a customer to loading saved data.
Examples
If you already signed up on the website and created classes in the dashboard, skip to “Create and Read Data”.
Signup and App
First, we have to create a customer object that represents YOU, the developer / app admin, with the example name “admin0815″, which can later be used to log in at web.apiomat.org:
curl -vX POST https://apiomat.org/yambas/rest/customers \ -d name=admin0815 -d email=admin0815@example.com -d password=123456
The email/password combination is attached to all futher commands with the -u parameter. It gets Base64-encoded and is used for HTTP Basic Auth.
When sending a POST request and thus creating a new object on the backend you can get the URL of the created object from the location header of the response.
To use the created customer “admin0815″ any further you need to make sure that you accepted all EULA requirements which were set by administrator.
After accepting the EULA e.g. via Dashboard login you can continue to create an app with the name “TodoList”, which is going to contain all classes and data later:
curl -vX POST https://apiomat.org/yambas/rest/customers/admin0815/apps \ -d name=TodoList -u admin0815@example.com:123456Now set the app to active state (it is inactive initially):
curl -vX PUT https://apiomat.org/yambas/rest/customers/admin0815/apps/TodoList \ -d "{\"applicationStatus\":{\"TEST\":\"ACTIVE\",\"LIVE\":\"ACTIVE\"}, \"applicationName\":\"TodoList\"}" \ -u admin0815@example.com:123456 -H "Content-Type: application/json"
Now send a GET request to the newly created app. The returned JSON contains a so-called API-Key for each System (LIVE, STAGING, TEST), in this case we’re going to use the “liveApiKey”:
curl -v https://apiomat.org/yambas/rest/customers/admin0815/apps/TodoList \ -u admin0815@example.com:123456
Create Classes
Now we can create some classes (also called meta models in a ApiOmat context).
First, we create a Module called MyTodoList containing our classes:
curl -vX POST https://apiomat.org/yambas/rest/modules/ \ -d moduleName=MyTodoList -d customerName=admin0815 -u admin0815@example.com:123456
Now, let’s create a class called Todo:
curl -vX POST https://apiomat.org/yambas/rest/modules/MyTodoList/metamodels \ -d metaModelName=Todo -u admin0815@example.com:123456
Save / remember the meta model ID that is in the URL of the location header of the response.
The Todo class now gets a description attribute of type string. For the request url use the meta model ID from before here:
curl -vX POST https://apiomat.org/yambas/rest/modules/MyTodoList/metamodels/<METAMODELID>/attributes \ -d attributeType=String -d attributeName=description -u admin0815@example.com:123456
You may add more classes and attributes here (for a Todo class a done and untilDate atttribute would make sense).
If you are ready, deploy your app (in our case using the LIVE system):
curl -vX PUT https://apiomat.org/yambas/rest/modules/MyTodoList \ -d "{\"moduleStatus\":{\"LIVE\":\"DEPLOYED\"}}" -u admin0815@example.com:123456 \ -H "Content-Type: application/json"Create and Read Data
Now all classes are created and you could download the SDK and continue with it or continue with using the REST API directly.
Choosing the latter option, we’re going to add some data now. Therefore we need the API-Key. This was in response to the creation of the App. If you didn't happen to write it down you can also find this key in the Dashboard by clicking "Configuration" beneath the app backend name.
In the following snippet please note that in Linux, cURL expects you to escape the $ sign, so you need to use "MyTodoList\$Todo", but in Windows you need to use "MyTodoList$Todo".
curl -vX POST https://apiomat.org/yambas/rest/apps/TodoList/models/MyTodoList/Todo \ -d "{\"@type\":\"MyTodoList\$Todo\",\"description\":\"Write REST API introduction\"}" -u admin0815@example.com:123456 \ -H "Content-Type: application/json" -H "X-apiomat-apikey:<APIKEY>"
Again, you can find the URL for your created Todo object in the location header of the response, which contains the ID of the newly created object. You can use this URL directly to send a GET request:
curl -v https://apiomat.org/yambas/rest/apps/TodoList/models/MyTodoList/Todo/<OBJECTID> \ -u admin0815@example.com:123456 -H "Content-Type: application/json" -H "X-apiomat-apikey:<APIKEY>"
The response body contains the data that you requested, as JSON. But that’s not only the attribute that you created, but also attributes like the time the object was created and modified, as well as other data:
{"@type":"MyTodoList$Todo","createdAt":1397658272500,"lastModifiedAt":1397658272519,"id":"123e92a0e4b02da9c2b6f321","applicationName":"TodoList","ownerUserName":"admin0815@example.com","moduleName":"MyTodoList","allowedRolesRead":[],"allowedRolesWrite":[],"allowedRolesGrant":[],"restrictResourceAccess":false,"referencedHrefs":{},"description":"Write REST API introduction","href":"https://apiomat.org/yambas/rest/apps/TodoList/models/MyTodoList/Todo/123e92a0e4b02da9c2b6f321"}
Okay, that’s it for now. We hope this helped you to understand how to use our REST API. If you have any questions don’t hesitate to contact us.
Have fun coding!