Ermeo made up of two products: the platform and the application. The very first thing to understand about the Ermeo API is that this platform and this application are completely based on this API. This means that the platform and the application are not directly connected, but instead use this API to exchange data that is stored in a database.
This way, the API is the interface between you (via the application or the platform) and the data you have access to. The API used by the platform and the application is the same we give our clients access to. Therefore, if you are asking yourself:
Can I do this with the API?
and the platform and the application can already do it, you will be able to do it thanks to the API.
1. Prerequisites
A few things are needed in order to start working with our API:
- The most obvious one is to have a minimum of technical skills, or at least knowing what an API is and already having worked with one.
- Understand the basics of Ermeo. There are trainings provided by our team. If you have not been trained or do not know anything about Ermeo, please ask for these trainings to avoid a waste of time during the development of your connectors.
- Have a look at our API documentation .
- A test environment. It is in general a very bad practice to test an API on a production environment. This is why we have the ability to provide you a test environment, where you can test everything you need in order to start working on your connectors. Please note that these environments are no where near the production environment in terms of performance. These are for testing purposes only.
2. API basics
As we saw before in this article, the platform and the application only use our API to work. This means that all the entities (assets, users, jobs, ...) are accessible with our API. Each of these entities have their proper CRUD (Create, Read, Update, Delete) routes. In Ermeo, most of the main entities have the following routes:
- GET /entities allows you to access all the items corresponding to the entity you want to retrieve. For example: GET /assets will return all the assets you have access to.
- GET /entities/{id} allows you to access a specific item corresponding to the entity you want to retrieve. For example, GET /assets/1247d918-3cd5-476d-a432-88273e3173d5 will retrieve a specific asset.
- POST /entities/search allows you to search for a list of items corresponding to the entity you want to retrieve. The fact that this request is a POST allows you to pass a filter in the body of the request. For example, POST /assets/search will return all the assets according to the filter you sent in the body of the request.
- PUT /entities/{id} allows you to update a specific item corresponding to the entity you want to update. For example, PUT /assets/1247d918-3cd5-476d-a432-88273e3173d5 will update this specific asset according to the information you sent in the body of the request.
- DELETE /entities/{id} allows you to delete a specific item corresponding to the entity you want to delete. For example, DELETE /assets/1247d918-3cd5-476d-a432-88273e3173d5 will delete this specific asset.
These requests are examples of what you can do with the Ermeo API. Of course, other requests are also provided depending on the type of entity you want to work with. Everything you should know is listed in the API documentation.
An authentication system is here to secure the requests and the data you receive and send. Indeed, every request needs to be authenticated in order to receive a response from the API. Please follow this article in order to learn more about how to authenticate your requests.
3. Start working with the API
As mentioned previously in this article, the very first thing you need to have is a test environment. This should be provided to you alongside with a client_id and a client_secret, used to create an access token that will be needed to authenticate your requests.
Once you have this environment, you are good to go. Before starting to develop anything, we recommend to use Postman to get familiar with our API by testing a few routes listed in the API documentation .
Postman is a tool available on Windows, Mac and Linux used to consume APIs that can be downloaded here. Once this is downloaded, you can start the tool. Once you launch Postman, you will be prompted to sign in or create an account. If you want to skip this step, you can:
You should now arrive on the main screen of Postman. From here, you can start creating a new collection and new requests.
If you have taken a look at the API documentation, you notice that it is divided in 7 parts:
- Login to Ermeo
- Manage your attributes
- Manage your databases
- Manage your documents
- Manage your users
- Manage your jobs
- Connect to other softwares
We recommend to import each one of these parts into Postman, so you have access to all the requests you need directly pre-configured. In order to do so, for each part, click on ”Export Bundled References”:
This should open a new page containing text in the YAML format. Copy the URL of this page. In Postman, click on the Import button:
Select ”Link”, paste the link from the API documentation you copied earlier and click on Continue
And finally click on ”Import”
You should now have access to all the requests of a part in a Postman Collection and start using them
Once you have imported all the parts of the API documentation, you are good to start working with the Ermeo API!
There are of course many ways to work with our API and many tools are available on the Internet for that. As a direct competitor of Postman, we have Insomnia, an open-source API client available to download here.
We can also work with ETL (Extract, Transform, Load), the most famous ones being:
Of course, the other possibility is to develop your own connectors from scratch using the technology you want (Javascript, PHP, .NET or basically any language or framework you wish).
4. Good practice and tips
4.1. Read all the articles in this section
Once you get familiar with the different routes of our API, you will start thinking about the workflow you want to build. Before you go any further, please read the following articles, they may help you a lot as they cover most of our clients use cases in terms of API integrations:
- Login to the Ermeo API and start sending requests
- Synchronise your assets with Ermeo
- Synchronise your jobs and reports with Ermeo
- Synchronise your users with Ermeo
4.2. Don't send several requests at the same time
When creating your connector on a test environment, keep in mind that this environment is slow compared to the production environment. This is why the execution time of your connector will be way faster once it is deployed on your production workspace. Don't send several requests at the same time, and always wait for the API to respond before continuing your workflow. This will save resources on your side as well as ours.
4.3. Use the Network of your browser when navigating on the platform
Our API documentation is very complete in terms of how to use each of the routes accessible with our API. But there is not a better help than seeing all the requests sent by the platform to our API. In order to see this, go to the Ermeo platform, right-click anywhere on a page and select Inspect. Once this is done, select the Network tab, then select Fetch/XHR and finally filter out all SVG requests done to our API by entering -.svg in the filter input:
Then, by navigating in the platform, you will see all the requests sent to our API. Remember that this API is the same as the one you can use! So feel free to check them out, see the requests bodies, headers and parameters as well as the responses of the API.