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. You can either have a look at the public one on https://cloud.apiomat.io/apidocs or on your on-premise installation, where the URL is something like https://apiomat.yourcompany.com/apidocs.
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 separated 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.
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
As URL we'll use https://apiomat.yourcompany.com as example. Please replace that URL by either the cloud version (https://cloud.apiomat.io) or the actual URL of your ApiOmat on-premise installation.
If you already have an account and created classes in the dashboard, skip to “Create and Read Data”.
Signup and App
First, you need an account that represents YOU, the developer / app admin, with the example name “admin0815″, which can later be used to log in at https://apiomat.yourcompany.com.
This can either be done with the SuperAdmin or an organization account.
Bash
curl -v -X POST -u SuperAdmin:secret -d name=admin0815 -d email=admin0815@yourcompany.com -d password=123456 https://apiomat.yourcompany.com/yambas/rest/customers
The email/password combination of your account is attached to all further 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 the SuperAdmin.
After accepting the EULA (for example via Dashboard login) you can continue to create an app with the name “TodoList”, which is going to contain all classes and data later:
Bash
curl -v -X POST -d name=TodoList -u admin0815@example.com:123456 https://apiomat.yourcompany.com/yambas/rest/customers/admin0815/appsNow activate the app (it's inactive initially to not accidentally expose an unfinished app):
Bash
curl -v -X PUT -d "{\"applicationStatus\":{\"TEST\":\"ACTIVE\",\"LIVE\":\"ACTIVE\"}, \"applicationName\":\"TodoList\"}" -u admin0815@example.com:123456 -H "Content-Type: application/json" https://apiomat.yourcompany.com/yambas/rest/customers/admin0815/apps/TodoList
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”:
Bash
curl -v -u admin0815@example.com:123456 https://apiomat.yourcompany.com/yambas/rest/customers/admin0815/apps/TodoList
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:Bash
curl -v -X POST -d moduleName=MyTodoList -d customerName=admin0815 -u admin0815@example.com:123456 https://apiomat.yourcompany.com/yambas/rest/modules/Now, let’s create a class called Todo:Bash
curl -v -X POST -d metaModelName=Todo -u admin0815@example.com:123456 https://apiomat.yourcompany.com/yambas/rest/modules/MyTodoList/metamodelsSave / 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:Bash
curl -v -X POST -d attributeType=String -d attributeName=description -u admin0815@example.com:123456 https://apiomat.yourcompany.com/yambas/rest/modules/MyTodoList/metamodels/<METAMODELID>/attributesYou 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):Bash
curl -v -X PUT -d "{\"moduleStatus\":{\"LIVE\":\"DEPLOYED\"}}" -u admin0815@example.com:123456 -H "Content-Type: application/json" https://apiomat.yourcompany.com/yambas/rest/modules/MyTodoList
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".
Bash
curl -v -X POST -d "{\"@type\":\"MyTodoList\$1.0.0\$Todo\",\"description\":\"Write REST API introduction\"}" -u admin0815@example.com:123456 -H "Content-Type: application/json" -H "X-apiomat-apikey:<APIKEY>" https://apiomat.yourcompany.com/yambas/rest/apps/TodoList/models/MyTodoList/v/1.0.0/Todo
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:
Bash
curl -v -u admin0815@example.com:123456 -H "Content-Type: application/json" -H "X-apiomat-apikey:<APIKEY>" https://apiomat.yourcompany.com/yambas/rest/apps/TodoList/models/MyTodoList/v/1.0.0/Todo/<OBJECTID>
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:
Json
{"@type":"MyTodoList$1.0.0$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.yourcompany.com/yambas/rest/apps/TodoList/models/MyTodoList/v/1.0.0/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!