ID4i API Developer Guide

User authentication is used for interactive sessions with ID4i, i.e. if a user uses some kind of graphical or commandline interface to perform tasks within ID4i.

API Key are used to allow automated processes to authenticate against ID4i. This is used for integration with other backend systems like ERPs or PIMs, smartphone apps or manufacturing devices. In this scenario, the client is responsible for creating the access token.

Authenticity is established by cryptographically signing the access token using either

To create a valid Application token, you need to provide the following JWT properties:

An example of how to create a JWT in Java using JJWT is shown below. Additional libraries for creating JWTs can be found at https://jwt.io/.

For further code samples please refer to Client Libraries.

All operations are guarded by permission checks. Permissions can be attached to users via predefined roles and to API Keys directly. User roles are given to users in the context of Organizations. A user belongs to all Organizations he has at least one role in. The currently predefined roles are:

The roles are given to a user via inviting him to an organization (Users → Invite Users) or editing when he is already part of the organization (Users → <User> → Edit) in the web UI. It is possible to invite users that are already registered in ID4i as well as inviting new users using their email address. New users will get an email and are prompted to finish their registration.

We do not support creating custom roles as of now. If you have additional requirements for roles, please get in touch.

There are two kinds of permissions: global permissions for certain actions (e.g. to create GUIDs or add and remove Aliases and read private routes) and permissions in the context of ID4iObjects like GUIDs and Collections (e.g. create, list, read and delete documents for a certain ID4iObject). Several permissions can be given either globally or per ID4iObject (e.g. write documents or data).

Per ID4iObject permissions are only supported for API Keys. For API clients, this allows you to give different clients different sets of permissions via API Keys. You can access the administration interface in the web UI at API Keys → <Key> → Edit.

The complete list of permissions can be found in the API key properties in the web interface and can also be obtained using the API at https://backend.id4i.de/docs/redoc/index.html/#operation/listApiKeyPrivileges.

The messages of a change log can be resolved in a specified Mimetype format. If the messages are rendered as e.g. text/mustache every ChangeLogEntry will contain messageProperties with a map of message property keys and corresponding objects/values.

Every message property that contains an object provides a value field that can be rendered regardless of the type provided. The following ID4i types can be interpreted:

All API endpoints are able to return both JSON and XML representations. The client decides which representation to use via the standard HTTP Accept: header.

To retrieve JSON, send the `Accept: application/json header, to retrieve XML send Accept: application/xml

The ID4i API supports English and German languages in the backend. This is primarily relevant for (error-) messages and emails sent from ID4i.

When logging in through the user interface, the language from browser locale is used to select the language for the UI and all subsequent API calls made from the UI to the backend.

When calling services through an other client, e.g. an Java, command line or Javascript application, the desired language can be specified in the Accept-Language header. Valid values are de and en. ` .Example: Invalid registration request German (curl)

All server side errors are returned as ApiError representations An API error contains an error code, a unique error id which can be used by support staff to find the occurrence of the error in the logs and a descriptive message. API errors can occur for technical (like problems with the infrastructure) and business reasons (like invalid or incomplete requests).

For more details, like existing error codes or nesting of errors, see ApiError.

Services that return potentially long lists of items can be used with server side pagination of results. i.e. the client does not request the complete list but rather a slice of it defined by an offset (the start of the requested result relative to the full list) and a limit (the number of items to be returned). The parameters are specified as query parameters in the URL.

Examples:

If you call a paginated resource without specifying offset and/or limit, the default values 0 for offset and 100 for limit are applied.

An example service that supports pagination can be found here: https://backend.id4i.de/docs/redoc/index.html#operation/listElementsOfCollection.

The response entities are wrapped into an object that states the given offset and limit parameters as well as the total number of elements. The actual result list is contained in the elements property. For examples see PaginatedResponseOfHistoryItem or PaginatedResponseOfGuid.

When holding back ownership of a collection, all it’s contained items' ownership is held back too.

When not holding back ownership of a collection while transferring it, ownership of it’s individual items is still being respected. That is, if a collection is transferred, including an item which was prepared for transfer and marked to hold back its ownership, the item’s public owner is unchanged - while only the holder changes. The collection itself and other items of the collection are of course unaffected by this item.

Holding back ownership is bound to the owner, not to the recipients. This means, that items of a collection which have the hold-back-ownership flag set but have a different set of recipients than the collection, keep their ownership when the collection is transferred. These items may have a completely disjoint or even empty set of recipients for the mechanism to work.

Private labelling can technically be applied multiple times on a single product. ID4i supports these cases in a way which respects the private labelling most closely to the customer best.

Assume an item is sent from a producing organization A to a private labelling organization B and from there to a second private labelling organization C, which in turn sends it to a reseller.

To be able to connect to ID4i with an API client, you need to register and set up an API key for your application first. Using this key, you can sign JWTs to send as Authorization header for subsequent requests.

To get started with a new project, you can have Maven generate a simple Java project for you using mvn archetype:generate. If you prefer, you can also use your IDE for that, obviously. In the following example, replace artifactId and groupId with your own values.

Maven will create an empty project that already compiles and runs unit tests. Run mvn install to make sure everything went well. Maven should report [INFO] BUILD SUCCESS.

Now we need to add two dependencies: One for working with JWTs and one for working with the ID4i API. While you could simply call all HTTP services using a plain HTTP client library, it may be simpler to use our pre-generated client. However, you are not forced to do so. You can also generate an own client using the OpenAPI specification at https://sandbox.id4i.de/docs/redoc/index.html.

To add these dependencies, add the following to the <dependencies> section of pom.xml:

If you want to use a -SNAPSHOT version to play with the development system, please talk to us. We can set you up to be able to do so.

If you run mvn install again now, you should see the artifacts being downloaded, e.g. like this: Downloaded: https://repo.maven.apache.org/maven2/de/id4i/api/id4i-api-client/0.1.1/id4i-api-client-0.1.1.jar Once this completes, you can use the ID4i java client library in your application.

The example code on GitHub also creates an executable jar containing all dependencies using the maven-assembly-plugin for easy distribution and deployment.

In this tutorial, we build a simple standalone application. Go to src/main/java/<package>/App.java, create a start(String[] args) method and call it from main().

Now that we have the infrastructure in place, we can create a JWT to send along with our requests as shown in JWT token creation using JJWT. To make ID4i recognize the key, you need to set the subject to your application key and sign with the secret you saved in the preparation step. For details on the other parameters see JWT token creation using JJWT. For the sake of this tutorial, we simply create one token and save it in a member of the application class. We create a token that is valid until two minutes in the future.

After creation, we simply print it to stdout to see that something happened. In the source code on GitHub, you can also find a corresponding unit test.

Run the application and it should print out something like Created access token eyJ0eXAiOiJBUEkiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJlOTRiMDA2LWQxZD…​

So, typically, you will provide the key as well as the secret via commandline arguments, configuration or environment variables. We use environment variables since they play together nicely with containerized deployments and can be supplied from a different (secured) source than the source code.

Let’s factor out the two parameters and get them using environment variables:

For our first call, we’ll use GET /api/v1/info which returns some information about the version of the application currently running. To construct our call, we need to

To set the authorization, we use the JWT created before: String authorization = "Bearer " + jwt; Note the Bearer prefix as defined in RFC 6750. For the language, en and de are supported, defaulting to en.

Congratulations! You just made your first API call! How awesome is that? And if something did not work out as expected, don’t worry, you can first look into How to troubleshoot failing API calls and/or contact us. We’re real humans and happy to help. See Getting Support for ways to reach out.

You are now ready to explore the available operations either based on the HTTP interface directly (see https://sandbox.id4i.de/docs/redoc/index.html) or by using the API client libraries' docs at https://github.com/BlueRainSoftware/id4i-api_client-java.

Before jumping into a more complete use case, let’s review what happened in the background when we called apiInstance.applicationInfo() and how we can influence that:

In addition to the Api Key (see API Keys) you created in the last tutorial, you will work with several ID4i items using the web interface; Collections, Organizations and Routing files.

Before starting with the tutorial, we’ll create a labelled collection to hold our batch of produced things and an organization we send our goods (along with the GUIDs) to. In reality, this organization would already exist in ID4i. For the sake of the tutorial, we create one of our own. You are free to reuse your default organization from the last tutorial in this one or to create a new one and a new API Key now.

First, (Step 1 in the sequence diagram above) we create the labelled collection called Product Batch using Menu → Collections → New Collection (Product Batch, Labelled Collection).

Then, we create an organization to act as reseller: Menu → Organizations → New Organization (Reseller).

We will create the rest of the required data as we go along in the tutorial.

After that, we set up a new project as we did in the first tutorial. But instead of putting our business logic simply in main, we create two application classes to separate Producer and Reseller as shown below. Each of these classes are set up like the main class in the previous tutorial.

You can find the finished source code of this tutorial at GitHub. You’ll note that we factored out some of the basics we learned in the first tutorial into reusable utilities.

The first thing we need to do is to create some GUIDs to work with. To find out how to create them, let’s have a look into to API documentation at https://backend.id4i.de/docs/redoc/index.html. There, we can either navigate using the items on the left or use the search. The operation we are looking for is here: https://backend.id4i.de/docs/redoc/index.html#operation/createGuid. There, we can find the HTTP resource, method, status codes and expected representations as shown below. So we learned that we want to call POST …​/api/v1/guids/ with a request body that contains some information about the GUIDs to create.

Now we have all the information to make an API call manually (e.g. using curl or postman) or to find corresponding calls in the client library:

Let’s call this operation using the client library, run GuidTutorial and see what happens.

It seems that this has not worked so far. Luckily, the ApiError tells us what happened. If you have set up your application as shown above, you should see something like the snippet below on your console. It contains an error code, a unique error id (which we, as the ID4i operations team can use to find the corresponding logs) and some additional messages.

So what we learn from this error is, that the validation of our request body failed. The fields length, count and organizationId may not be empty. If we would have read the API docs, we would have known that. But hey, so we got a chance to have a look at an error. We will probably need that at some point in time.

So we update our CreateGuidRequest to add the required information. We create 10 GUIDs of the length 128 characters for our reseller organization. The organization ID is the namespace you used when creating the organization. You can look it up again in the organization view. Make sure you use the organization id of the producer organization - it has to match the API key owner.

The updated call should look like the snippet below.

Unfortunately, this still does not work. We get an ApiError telling us we are missing the privilege to create GUIDs: ERR_AUTHORIZATION_MISSING_PRIVILEGES with the message Missing privileges: [CREATE_GUID]. So we need to find our API Key using the web interface and give it the corresponding permissions. Also make sure the API key is activated. Note that creating GUIDs is an operation that incurs charges, so make sure to try this on the sandbox first and make sure everything works as expected. Your application using a key with such a permission has the permission to create costs for your organization.

Then retry the request. Finally, we have created our first GUIDs.

Before moving on, let’s recap what we learned to far:

The next task is to add the created GUIDs to the collection we created manually earlier. After what we’ve learned in the previous chapter, this should be a little easier now.

The operation we need is Collections - add elements to labelled collection. For that, we will make our createGuids() method return the created GUIDs and put them into the collection. We’ll wire it up in our base application class GuidTutorial.

There is just one piece of the puzzle missing. We need to figure out the collection ID of the target collection. We can do so using the web interface again. Either use the view or the copy button beside the collection. Note that collections also use GUIDs as identification.

When running it, you will see that we need additional privileges again: [ADD_ELEMENTS_TO_LOGISTIC_COLLECTION, ADD_ELEMENTS_TO_COLLECTION]. So we need to head over to the API key management and add the permission ADD_ELEMENTS_TO_COLLECTIONS for our Product Batch collection to our key. We actually need only this one permission for the API key as we select the collection for which we add the permission explicitly.

After having done so, run the application again. it should finish silently now. To see what happend open the collection in the UI and admire the beautiful GUIDs your API client created.

In this chapter, we …​

In the next step, we will create a logistic collection using the api client to prepare a shipment to our reseller.

To be able to transfer the ownership of GUIDs to another organization, we can put them into a logistic collection. Logistic collections model actual, physical shipments of goods. You can think of a logistic collection of an inventory of a package. When sending this package out, you will set a flag on the collection to allow it to be claimed by the receiving party. Once the receiver (our Reseller) opens the package, he can access the IDs and set his own organization as owner. Typically, this is done when putting the received items in stock (by an API client attached to a scanner).

So, the first step is to create a logistic collection. You will figure out which operation to call, which permissions you need and how to get them.

The result should look similar to this. If you look into the collection, you will see it is empty.

Also note that this operation creates a new collection for each run. So don’t get lost and clean up after yourself.

In the next step, we pick some of the IDs we created earlier and add them to the shipment collection. This could happen by someone in the warehouse scanning items he puts into a package. For simplicities sake, we just add all GUIDs we created before.

Note that we did not specify a collection type (labelled, logistic, routing) in our API operation. For collections, there are operations that check the collection type, thus providing additional safety against errors. However, since collections of all types also share a majority of their capabilities, there is also a generic version for the common operations like create, rename, add elements and delete.

After integrating the code in GuidTutorial (producerApp.putGuidsIntoCollection(guids, shipmentCollectionId.getId4n())), we can run it and see that our GUIDs where put into our logistic collection.

Lastly, when we are ready to ship the package and make its contents claimable by the receiving party, we prepare a transfer and set the open-for-claims flag. This allows any organization to claim the GUID. It is typically used when moving an item internally within organizations (departments, in this case) of the same company. To restrict which organizations may claim the item, you have to set the recipientOrganizationIds field to a list of organizations that may receive the transfer.

If you set keepOwnership to true, the sending organization will keep the ownership; the receiver will be the holder , not the owner after he claims the GUID. You would do this if you send an item to a contractor or partner to process the without actually selling it. See Transfer for details.

This concludes the Producer part of the process. We created the GUIDs, put them into a collection for our internal management and created a second collection to hold the GUIDs. We are now about to ship to our Reseller and allowed the next party to claim the items.

The complete flow is visible in GuidTutorial.

Now we assume all the items corresponding to the GUIDs in the logistic collection have been sent to the reseller. Upon receipt, the package is opened and all items are scanned. The Reseller application is hooked up to the scanner and is responsible for taking the ownership of these items.

To take the ownership, the receiving party simply receives the GUID transfer to set her own organization id. This is only possible if the sending organization made the GUIDs transferable by setting open-for-claims flag or included the receiving organization in the recipient list.

The code to claim ownership for one item could look like this.

Next, we want to add some additional means for identifying our GUIDs. We use Aliases to add an internal item number to some of the GUIDs and a GTIN to some others.

After we call that new method in our Reseller app, we can search for the aliases using the UI (or the search API operations).

These aliases can be used later to set up routes to information about GUIDs hosted in external or third party systems, like a web shop, an internal ERP or PIM system, a manufacturing machine on the shop floor or a delivery tracking service, to name just a few. We’ll see how to set up Routing in the following tutorial.

Before we get to that, let’s recap what happened on the reseller side and what we implemented to support it:

We learned how to set up processes spanning multiple organizations using ID4i as a central backend for single workpiece related information. The process we looked at was pretty simple, but the basic mechanics needed to implement large scale processes were covered.

Stay tuned for the next tutorials covering Routing and data exchange using Storage.

To get started, log in to ID4i, create a new routing collection, add some GUIDs and open the collection’s routing file. We’ll do this using the user interface. If you want to create Collections and add existing GUIDs - instead of adding new ones - using your own API client, have a look at the previous tutorial about working with GUIDs and Collections.

You will now see an editor with an empty routing file.

We will create the first route using the editor in the UI. Alternatively, we can construct a routing file using the API client library or simply write it as JSON in an editor of your choice and upload it using https://backend.id4i.de/docs/redoc/index.html#operation/updateRoutingFile} We’ll use the programmatic approach in a following step later on.

We can use the example routing file from Routing as a starting point and copy it into the right editor pane. You can either edit the JSON source directly in the right pane or use editor controls in the left one. Use the buttons at the bottom to copy the contents back and forth between the two panes. Upon saving, the contents of the left pane are stored.

So go ahead, copy the example from Example Routing File and play around with editor for a bit. Also create some invalid content and look at the validation messages.

Our first public route will search google for our ID. To do so, remove all routes but one and set its properties as follows and save the routing file. Note that the parameter {id4n} will be interpolated to match the GUID that is routed. For further details on the contents see Routing.

To test this route, open the QR code of a GUID from the routing collection and click Open or scan the code with a mobile device. This will send you to a google search for the GUID - which will probably return nothing too useful.

So let’s fix that by searching for a public product alias, the GTIN. Also, let’s search on Amazon instead of using Google. We will change the URL to https://www.amazon.de/s/&field-keywords={alias_gtin}, save the routing file and run the search again. But instead of doing this in the editor, we’ll retrieve the route definition using an API client, change it and upload it again. We will also add the GTIN alias (as already shown previously) to be able to use it in that route. To be able to do that, you may need to give your API key additional permissions.

We’ll need two IDs to be able to make our API calls: the GUID we want to route and the ID of the routing collection.

You can set up a new client project as shown in the first tutorial or reuse an existing one. Or just hop over to GitHub and use the sources from there.

Now we want to modify the route and upload it again. You’ll notice that the URL is hidden in a Map inside a route. This is because route objects can be used for very different kinds of routes that can need arbitrary data. You can use this map to attach information to routes and use them in your API client when you are talking to systems to integrate.

After you ran that code, open the web interface again to see your changes reflected in the routing file editor. You need to reload the collection detail page for that.

Open the GUIDs QR code again and see where it redirects you to now. Note that code/ the URI it links to did not change. It always points to the public /go service for the GUID which figures out which route to use.

Here is what happened behind the scenes when you were following the link in the QR code.

If you want to work with private routes, the principles are the same: You set up your routing rules, request the rules from the routing service and redirect calls to the returned route. By doing so, you are able to define and reuse routes in ID4i but also call internal systems that are not exposed to the internet. They only have to be available from the network your client runs in, allowing for secure integration between internal and external systems using ID4i.

Let’s create a private route with custom (i.e. API client defined) routing parameters using our API client. Then, we simply add it to the RoutingFile object we retrieved earlier and push it back to the server.

You can review the change you just made in the routing file editor.

You can add any number of routes to a routing collection. However, at any given time, there is only one route per type active per GUID based on the priority. The routing service we will now query will always return the route with the highest priority of the given type. You can also request routes as they would be seen by an different organization if you / the API key has the corresponding permissions.

We can now retrieve the route again. Typically, defining routes and using them will be two distinct concerns and be implemented in different API clients. Often, the route definition will just be a manual configuration task in the UI.

To recap what we did in this tutorial: You learned how to …​

The complete sources of this tutorial can be found on GitHub

Let’s start by attaching documents. We assume you already have an ID4i account and API Keys with the CREATE_DOCUMENTS permission set up. We’ll also skip initializing the client, please refer to the previous tutorials for that.

We first create a GUID, then we add a document from the classpath.

The created document should look like the following snippet on the console. If you search for the GUID in the web interface, you will now see this document as shown in the screenshot.

But what does the lock icon and the visibility section in the JSON representation mean? You will have guessed that the visibility controls who can view the document. If __public is set to true, the document is publicly available. You would use this e.g. for official data sheets. If it is false only members of your organization having the permission to read documents (READ_DOCUMENTS, obviously) can see it. For details on what happens if you transfer documents to another organization and shared visibility, see Transfer and Private Labelling. Note that per default, the visibility is private.

Now, if you want to publish the document, you need to update the visibility like this. If you want to use sharing, please read Transfer and contact us so we can tell you more on how to acquire the sharing module.

In the sample on GitHub, we uploaded two documents and published one of them as shown in the screen shot below.

Micro storage is a small amount of space (1kB) that can be used to transfer arbitrary data. Data in micro storage is always private and cannot be shared. You’d typically use it along the manufacturing process to let workstations / machines exchange data regarding a GUID.

Using it is simple as you can see from the following snippet.

In this tutorial, we have seen how to …​

The complete sources of this tutorial can be found on GitHub

When running JS in the browser, open your developer tools and look into the network connections. We like to use Chrome, but other browsers have these, too, obviously.

Locate the failing request (it should be highlighted in red) and select it. You can now see all the headers that where exchanged and the API Error representation. There should be a useful error message in there. It also has an error code and a unique error ID. If you contact us, please let us know these, so we can find the corresponding log events easily.

You can copy the complete request in various formats (e.g. curl and HAR) to play around with in other tools by using the context menu on the failed request as shown below. Note that you can simply import a curl commandline into Postman, which is incredibly useful. Thanks, social media: https://twitter.com/adrian_philipp/status/710438593936932864

For each simple API operation, there is a variety withHttpInfo that contains additional information. One simple way to see what is going on is to temporarily use this one and inspect the contents using your debugger. For example, a call like AppInfoPresentation result = apiInstance.applicationInfo() would become ApiResponse<AppInfoPresentation> result = apiInstance.applicationInfoWithHttpInfo()

If this is not sufficient, you want to look into the library code at the location where the call is executed. This is de.id4i.ApiClient#execute(com.squareup.okhttp.Call, java.lang.reflect.Type). The Call object has all the information needed as shown in the screen shot below.

In case the call completely fails (as opposed to just not behaving as expected), you can look into the thrown ApiException. Its body corresponds to an ApiError object like in the JS example above.