Rest API (JSON)
This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial.
This page describes the steps you need to take to integrate with the standard Metamaze API. This page serves as a tutorial. Connection through the API of Metamaze is possible via token authentication or mutual TLS certification. For technical details on how to implement it, see the Metamaze API documentation.
For this tutorial, we will use Postman to perform the API request.
API integration using token authentication
Step 1: Configure the input API and get a Bearer token
Create (or refresh) a new Bearer token by clicking the two blue arrows
Copy the Bearer token and store it for later use
Click Save to store the generated Bearer token
Step 2: Find your organisationId and projectId
You can find the organisationId and projectId in the URL of e.g. the project settings:
Step 3: Base64 encode your document
To add documents to your JSON API request, you need to base64 encode them. In Linux and on Mac OS X, you can just run
> base64 <inputfile>
Tip: to immediately copy the base64 encoded file to your clipboard you can use
> base64 <inputfile> | pbcopy
Step 4: Create your request to start processing
In Postman, create a new request.
Change the type from GET to POST
Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process where
{{organisationId}}
and{{projectId}}
are the values from Step 2.Under the Authorization tab, choose Bearer Token as the type. Fill in the generated Bearer Token from Step 1.
Under Body, change the type to raw and select JSON as the body format.
Add the following request body where you replace
{{base64 encoded file}}
with the output from Step 3. You can add optional metadata too
In Postman, you can click "Code" (top-right, under the Send and Save buttons) to quickly export your API call to the most popular programming languages immediately.
6. Click Send to send the request. You will receive a response like this with status code 200. Store the uploadId: you will need it to fetch the status and the results
Step 5: Create a new request to fetch the results
In Postman, create a new request.
Set the request type as GET now.
Set the request URL to https://app.metamaze.eu/gql/api/organisations/{{organisationId}}/projects/{{projectId}}/process/{{uploadId}} where
{{organisationId}}
and{{projectId}}
are the values from Step 2, and{{uploadId}}
is the ID you received in the response of Step 4.As above, add the Bearer Token authentication.
Click Send to send the request and fetch the results.
You will find the extracted values under
documents[].aggregatedEntities
.
Summary
In this tutorial, we showed the easiest way to integrate Metamaze. For other topics like receiving results immediately (push instead of pull), advanced authentication, restricting document types, uploading training data or adding metadata you can find information in the full API documentation.
Generating certificates for requests to Metamaze with mTLS
In the tutorial above, authentication was with a Bearer token. You might want to consider to add certificate-based authentication for an additional layer of security.
This guide provides step-by-step instructions on generating certificates using SSL for secure communication with Metamaze using mutual TLS (mTLS).
Step 1: Generating a key and a Certificate Signing Request (CSR)
To generate a key and a CSR, please follow the command given below:
Keep your client.key
file private and protected.
Step 2: Send the CSR to Metamaze Support to sign with our CA
After generating a CSR, you can open a support ticket via the information provided on Getting support. In that support ticket, include the client.csr
file as an attachment and ask to sign it.
After verifying your information, Metamaze will sign the CSR and provide you with a signed certificate.
For reference, we will use a command similar to:
Step 3: Add the certificate content to Metamaze
After generating the client.crt
file, you can paste the content of it in the Metamaze project settings > Input > REST API. The certificate should have the following structure:
Step 4: Test API calls in Postman
To configure Postman correctly with mTLS, follow these steps:
In Postman, navigate to Settings > Certificates and click "Add Certificate"
Enter the following information
Add HOST
*.metamaze.eu
Add CRT file
client.crt
that was provided by MetamazeAdd your KEY file
client.key
Leave PFX file empty
(Optional) If you set a passphrase when generating the key, add the passphrase here too.
Postman automatically looks at the hostname of every API call to decide if client authentication is needed. By adding the host *.metamaze.eu, all API calls will be covered.
For testing purposes, we provide an endpoint at app.metamaze.eu/test-ssl
that you can use. When sending a POST request to that endpoint with an empty body, you should receive a response similar to
Overview of files
At the end of the process, you will have the following files:
client.csr
(not needed anymore, it was used for step 2 only)client.key
(use this to sign the request to Metamaze, keep this private)client.crt
(used to validate the request in Metamaze, to be pasted in the project settings.)
Please note that both the client.key
and client.crt
files are necessary for secure communication with Metamaze and should be kept securely.
Note that self-signed certificates are not supported. Certificates for client authentication using mTLS must be signed by the Metamaze Certificate Authority.
Last updated