Upload
others
View
2
Download
0
Embed Size (px)
Citation preview
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 2/181
Table of contents
BOC Management Office Standard RESTful Services........................................................... 1
1 Introduction .................................................................................................................... 6
2 Architecture ................................................................................................................... 6
3 General Information ....................................................................................................... 7
4 Technical Overview ....................................................................................................... 7
5 Authentication ................................................................................................................ 9
5.1 Token Based Authentication .................................................................................. 9
5.2 Basic Authentication .............................................................................................11
6 Compatibility Changes between Versions .....................................................................11
7 Set Up Authenticated Access to BOC Management Office Product ..............................14
7.1 Install BOC Management Office Product ...............................................................14
7.2 Create Technical User in the Administration Toolkit ..............................................14
7.3 Assign Access Rights to the Administration Toolkit ...............................................15
7.4 Edit System Settings .............................................................................................16
7.5 Edit Settings for Standard RESTful Services .........................................................16
7.6 Standard RESTful Services – Tokens ...................................................................17
7.6.1 Rest Security Context .................................................................................................... 18
7.6.2 Cache Path .................................................................................................................... 19
7.7 Standard RESTful Services – Basic Auth ..............................................................19
7.7.1 Enable Basic Authentication .......................................................................................... 20
7.7.2 REST Scenarios ............................................................................................................ 20
7.8 Assign Web Module to all Users ...........................................................................20
7.9 Enable Basic Authentication for BOC Management Office Products .....................21
8 REST Service ...............................................................................................................22
9 Repository Read APIs ..................................................................................................23
9.1 Repositories ..........................................................................................................23
9.1.1 HATEOAS Links ............................................................................................................ 23
9.1.2 Repositories Result Example ........................................................................................ 23
9.2 Statistics ...............................................................................................................25
9.2.1 HATEOAS Links ............................................................................................................ 25
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 3/181
9.2.2 Statistic Result Example ................................................................................................ 26
9.3 Model Group .........................................................................................................27
9.3.1 HATEOAS Links ............................................................................................................ 28
9.3.2 Model Group Result Example ........................................................................................ 28
9.4 Object Group ........................................................................................................39
9.4.1 HATEOAS Links ............................................................................................................ 40
9.4.2 Object Group Result Example ....................................................................................... 40
9.5 Model ....................................................................................................................48
9.5.1 HATEOAS Links ............................................................................................................ 49
9.5.2 Model Result Example ................................................................................................... 49
9.6 Object ...................................................................................................................56
9.6.1 HATEOAS Links ............................................................................................................ 57
9.6.2 Object Result Example .................................................................................................. 57
9.7 Modelling Object ...................................................................................................64
9.7.1 HATEOAS Links ............................................................................................................ 65
9.7.2 Modelling Object Result Example.................................................................................. 65
9.8 Model/Object/Modelling Object Link ......................................................................71
9.8.1 HATEOAS Links ............................................................................................................ 71
9.8.2 URL Result Example ..................................................................................................... 72
9.9 Model Image Map .................................................................................................73
9.9.1 HATEOAS Links ............................................................................................................ 74
9.9.2 Image Map Result Example .......................................................................................... 74
9.10 Object Usage ........................................................................................................78
9.10.1 HATEOAS Links ............................................................................................................ 78
9.10.2 Object Usage Result Example ....................................................................................... 79
9.11 Object Relations....................................................................................................83
9.11.1 HATEOAS Links ............................................................................................................ 84
9.11.2 Object Relations Result Example .................................................................................. 84
9.12 Object Relation Endpoints .....................................................................................87
9.12.1 HATEOAS Links ............................................................................................................ 88
9.12.2 Object Relation Endpoint Result Example .................................................................... 88
9.13 Object Relation Endpoint Details ...........................................................................92
9.13.1 HATEOAS Links ............................................................................................................ 93
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 4/181
9.13.2 Object Relation Endpoint Details Result Example ........................................................ 93
10 Repository Write APIs ...................................................................................................98
10.1 Repository Objects ................................................................................................98
10.1.1 Create Object ................................................................................................................. 98
10.1.2 Delete Object ................................................................................................................. 99
10.1.3 Modify Object ............................................................................................................... 100
10.1.4 Move Object ................................................................................................................. 101
10.2 Object Group ...................................................................................................... 102
10.2.1 Create Object Group ................................................................................................... 102
10.2.2 Delete Object Group .................................................................................................... 103
10.2.3 Modify Object Group .................................................................................................... 103
10.3 Object Relations.................................................................................................. 106
10.3.1 Create Endpoint ........................................................................................................... 106
10.3.2 Update Endpoint .......................................................................................................... 108
10.3.3 Delete Endpoint ........................................................................................................... 109
11 Repository Search APIs .............................................................................................. 109
11.1 Search Queries ................................................................................................... 110
11.1.1 Performing a Generic Search Query ........................................................................... 110
11.1.2 HATEOAS Links .......................................................................................................... 111
11.1.3 Result Examples for a Simple Query........................................................................... 111
11.1.4 Filters Definition ........................................................................................................... 116
11.2 Search Jobs ........................................................................................................ 117
11.2.1 HATEOAS Links .......................................................................................................... 118
11.2.2 Prepare Query ............................................................................................................. 118
11.2.3 Fetch Query Result ...................................................................................................... 119
11.2.4 Delete Query Result .................................................................................................... 120
11.2.5 Example ....................................................................................................................... 120
12 User Read APIs .......................................................................................................... 125
12.1 User group .......................................................................................................... 125
12.1.1 HATEOAS Links .......................................................................................................... 126
12.1.2 User Group Result Example ........................................................................................ 126
12.2 Roles .................................................................................................................. 134
12.2.1 List of Role Grouping Items ......................................................................................... 134
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 5/181
12.2.2 List of Roles inside Grouping Item............................................................................... 136
12.2.3 Detailed Role Information ............................................................................................ 138
12.3 Users .................................................................................................................. 141
12.3.1 Get the Specified User ................................................................................................ 141
12.3.2 Users List ..................................................................................................................... 148
13 User Write APIs .......................................................................................................... 150
13.1 Users .................................................................................................................. 150
13.1.1 Create Users ................................................................................................................ 150
13.1.2 Delete Users ................................................................................................................ 153
13.1.3 Modify Users ................................................................................................................ 153
14 Error Handling ............................................................................................................ 158
15 Appendix .................................................................................................................... 158
15.1 Sample Implementation (Java): Programmatic Access ....................................... 158
15.2 Sample Implementation (Java): Authenticated REST call ................................... 159
15.3 Sample Implementation (Java): Using HTTP POST ............................................ 162
15.4 Sample Implementation (Java): Using HTTP POST to Create a New User ......... 163
15.5 Sample Implementation (Java): Using HTTP GET to Get Model Data ................. 166
15.6 Sample Implementation (Java): Using HTTP POST to Create a New Object ...... 170
15.7 Sample Implementation (Java): Using HTTP PATCH to Update an Existing Object 174
15.8 Sample Implementation (Java): Using HTTP POST to create a Relation between two Existing Objects ....................................................................................................... 177
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 6/181
1 Introduction BOC Management Office products offer a generic, extensible REST API that allows authenticated access to exposed functionality in the BOC Management Office product.
This document explains how use this REST API to:
• set up authenticated access to the REST interface of the BOC Management Office product and
• send requests to the BOC Management Office product.
Note: Access to the application programming interface (API) is limited to 500 requests per hour.
2 Architecture
The picture shows the basic architecture of a BOC Management Office product:
Fig. 1: Architecture of a BOC Management Office product
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 7/181
• Access to the database is handled by the application server. • The application server offers an (internal) SOAP web service interface via
which its functionality can be accessed. • This SOAP web service interface is used by the web server to communicate
and exchange data with the application server. • The data is then presented to the user in the browser. To gain access to this
data, a user has to be logged in to the web client. • The web server itself exposes a RESTful interface to the outside world which
can be used by external components to retrieve or manipulate data specific to the BOC Management Office product.
3 General Information
REST stands for Representational State Transfer and is an architectural style for distributed systems.
It does not define a communication protocol, it is not a web service standard, and it is not a deployable technology.
RESTful services are resource oriented and stateless, meaning each request is self-contained. The communication is based on a request/response structure.
HTTP methods are used to send requests:
• GET for reading / querying resources. GET requests by convention do not modify business resources on the server (GET requests will of course still modify technical resources such as log files)
• POST for creating or updating resources. • PUT for creating or overwriting resources. • DELETE for removing content. • PATCH for changing a part of a resource. • HEAD for requesting metadata of a resource. • OPTIONS for evaluating which methods are available for a resource.
For additional information about REST: http://en.wikipedia.org/wiki/Representational_state_transfer
4 Technical Overview
BOC Management Office RESTful services are based on “JAX-RS”, a programming language API which facilitates creating a RESTful interface. BOC Management Office products use JAX-RS’ reference implementation “Jersey”.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 8/181
Jersey is very well documented. User guide: https://jersey.java.net/documentation/latest/index.html
API documentation: https://jersey.java.net/apidocs/latest/jersey/index.html
The addresses for RESTful services exposed by BOC Management Office products follow this pattern: http(s)://[Domain]:[Port]/[Product]/rest/[service path]
Where http(s)://[Domain]:[Port]/[Product]/rest/ is the fixed path and the part(s) afterwards are defined by the service.
Example
You are configuring ADONIS NP 8.0. You are running the ADONIS NP web application locally. The ADONIS NP web application exposes a REST service called “helloworld”. The URL should look like this:
"http://localhost:8000/ADONISNP8_0/rest/helloworld"
All registered services are listed in BOC Management Office products’ WADL description at .../rest/application.wadl.
Example
"http://localhost:8000/ADONISNP8_0/rest/application.wadl"
WADL is short for Web Application Description Language. For details, refer to:
http://en.wikipedia.org/wiki/Web_Application_Description_Language
https://wadl.java.net/
Important note: Accessing the WADL is only possible if the web application is operated in global debug mode. For information on how to activate global debug mode, please refer to the Web Client Administration Manual.
For testing purposes, the following URLs are always available: http://[Domain]:[Port]/[Product]/rest/connection http://[Domain]:[Port]/[Product]/rest/connection/auth (requires authentication - see below)
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 9/181
5 Authentication BOC Management Office RESTful services support two authentication mechanisms:
• Token based authentication: Each request is accompanied by Hashed security token to ensure validity of the request. Requests are executed in the context of a technical user.
• Basic authentication: Each request contains a header field of the form Authorization: Basic encodeBase64(username:password). Requests may be executed in the context of any standard product user.
5.1 Token Based Authentication
REST authentication is done using a security hash which is constructed from a public identifier of the client, a secret key of the client, a GUID and a timestamp of the request. This prevents that the REST functionality is used by unauthorized clients or that requests could be replayed or abused.
Each authenticated request to the REST API must contain following four headers in the request:
x-axw-rest-identifier
Shared identifier of the secret key defined for this client in the Administration Toolkit of the BOC product (see 7.6.1).
Example Value
Boc.rest.key.mfb.StandardRESTfulServices
x-axw-rest-guid
A GUID to ensure uniqueness of the request.
Generation Example
final String sGUID = UUID.randomUUID ().toString ();
aMethod.addHeader ("x-axw-rest-guid", sGUID);
Example Value d5dfba69-fab6-4156-9294-0c73ac20c5af
x-axw-rest-timestamp
The timestamp when the request was sent by the client. The header parameter 'x-axw-rest-timestamp' needs to be a UTC long value in milliseconds.
Generation Example
final long nDate = new Date ().getTime ();
final String sDate = String.valueOf (nDate);
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 10/181
aMethod.addHeader ("x-axw-rest-timestamp", sDate);
Example Value
1493365316885
x-axw-rest-token
Hashed security token to ensure validity of the request. For generation example, see below.
Example Value
QIYqykxHA2x+96qYf+S0w1suXswgtRMIquNMg6P6F3LAvbpwEB+23DD8iK1LVDsL6f2fIwxg+DK/pImDtowpeQ==
The algorithm for calculating the hashed security token consists of the following steps:
1. Get the secret key matching to the identifier sent via the x-axw-rest-identifier header.
2. Take all request parameter names and put them into a collection. 3. Take all request parameter values as strings and put them into the same
collection. 4. Take the header names x-axw-rest-identifier, x-axw-rest-guid and x-axw-rest-
timestamp and put them into the collection. 5. Take the values of the x-axw-rest-identifier, x-axw-rest-guid and x-axw-rest-
timestamp headers as well as the secret key and put them into the collection. 6. Sort this collection using Locale en_US. 7. Convert each item of the collection into a byte array using UTF-8 encoding.
(So in the end the whole collection should be converted from Collection<String> to Collection<byte[]>)
8. Append all items of the byte array collection into a single byte array in the order of their sorting.
9. Convert the secret key into a byte array using UTF-8 encoding. 10. Create a new HMac instance using SHA-512 algorithm. 11. Initialize the HMac instance using the secret key byte array. 12. Finalize the HMac using the byte array containing all parameters and
headers/parameters. 13. Get the resulting byte array of the HMac. 14. Convert the byte array into a Base64 encoded string using UTF-8 encoding.
For a sample implementation see section 15.2.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 11/181
5.2 Basic Authentication
Each authenticated request to the REST API must include an Authorization request-header field with the request. The Authorization field contains the username and password separated by a single colon (":") character, within a base64 encoded string.
Example Value Authorization: Basic encodeBase64(guest:Password123)
Note: As the credentials are only encoded and not encrypted, this method is not any more secure as sending the credentials in clear text. Therefore, use HTTPS in conjunction with basic authentication. Install the BOC Management Office product according to the Installation Manual and configure SSL/TLS support on Tomcat.
Basic authentication does not support login to the web client using an Identity Management System (IDM). Users with a colon in the username cannot be used for sending requests.
6 Compatibility Changes between Versions
For security reasons, the handling for authenticated requests was improved (made stricter) and the internal libraries that are used for providing the REST interface were upgraded with ADONIS NP 4.5 or higher and ADOIT 7.5 or higher.
Due to these steps, the REST interface behaves in a stricter way in certain areas:
• The header parameter 'x-axw-rest-timestamp' needs to be a UTC long value in milliseconds - previously it was possible to send a string with arbitrary data:
Before 4.5/7.5 4.5/7.5 or higher ...
final String sDate = new Date ().toString ();
aMethod.addHeader ("x-axw-rest-timestamp", sDate);
final Map <String, String []> aRequestParameters = new HashMap <String, String []> ();
aRequestParameters.put ("x-axw-rest-timestamp", new String [] {sDate});
...
final long nDate = new Date ().getTime ();
final String sDate = String.valueOf (nDate);
aMethod.addHeader ("x-axw-rest-timestamp", sDate);
final Map <String, String []> aRequestParameters = new HashMap <String, String []> ();
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 12/181
... aRequestParameters.put ("x-axw-rest-timestamp", new String [] {sDate});
...
• Both the REST client and the method defined in the server part have to be more strict than before concerning the sent/consumed ContentType. This is especially the case for sending of data using FormParameters. In previous versions, a client could send FormParameters to a defined method on the server without specifying any ContentType and the server method also did not need to specify a consumed ContentType:
Before 4.5/7.5 4.5/7.5 or higher
Server-side code: @POST
@Path ("/user_form")
@Produces (MediaType.TEXT_PLAIN)
public static String createUserForm (@FormParam ("username") final String sUsername,
@FormParam ("password") final String sPassword)
{
return createUser (sUsername, sPassword);
}
Server-side code: @POST
@Path ("/user_form")
@Produces (MediaType.TEXT_PLAIN)
@Consumes (MediaType.APPLICATION_FORM_URLENCODED)
public static String createUserForm (@FormParam ("username") final String sUsername,
@FormParam ("password") final String sPassword)
{
return createUser (sUsername, sPassword);
}
Client code ...
final String sSecurityToken = getSecurityToken (SECRET, aRequestParameters);
aMethod.addHeader ("x-axw-rest-token", sSecurityToken);
Client code ...
final String sSecurityToken = getSecurityToken (SECRET, aRequestParameters);
aMethod.addHeader ("x-axw-rest-token", sSecurityToken);
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 13/181
aMethod.setEntity (new UrlEncodedFormEntity (aPostForm, "UTF-8"));
final CloseableHttpResponse aResponse = aClient.execute (aMethod);
...
aMethod.addHeader ("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
aMethod.setEntity (new UrlEncodedFormEntity (aPostForm, "UTF-8"));
final CloseableHttpResponse aResponse = aClient.execute (aMethod);
...
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 14/181
7 Set Up Authenticated Access to BOC Management Office Product
The following steps are necessary in order to set up authenticated access to the REST interface of a BOC Management Office product:
7.1 Install BOC Management Office Product
• Install the BOC Management Office product according to the Installation Manual.
7.2 Create Technical User in the Administration Toolkit
Create the following technical user in the Administration Toolkit:
• User name: “Technical_StandardRESTfulServices” (and a password of your choice)
• Repository: Only (!) assign the repository to the user which holds the data to be queried.
• User groups: This user belongs to the default group. • System roles: If release workflows are licensed, and you want to use
repository write APIs, map the technical user to the “Administrator” roles: o ADONIS NP: Document Release Workflow and Model Release
Workflow o ADOIT: EA Workflow
• Trusted Login: Yes
Important note: You cannot activate “Trusted Login” during user creation. Only rights of already created users can be modified. Use the button “Create” in the “Create New User” tab to create the user before you activate “Trusted Login”.
Important note: Creating a technical user is necessary regardless of the authentication method, as it is required for loading the initial configuration.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 15/181
Fig. 2: Create technical user in the Administration Toolkit
7.3 Assign Access Rights to the Administration Toolkit
If you want to use user write APIs, you must assign access rights to the Administration Toolkit to the user in whose context requests should be executed.
Note: This can either be a technical user (for token based authentication) or a standard product user (for basic authentication).
In order to do so:
1. Right-click the user in the User Catalogue, and then click Change access rights.
2. Switch to the Components tab. 3. The momentary rights status for the Administration Toolkit is shown in the
column Rights. Double-click here until you reach the status Access. 4. When asked whether the user shall receive global administration rights, click
No.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 16/181
Fig. 3: Assign Access Rights to the Administration Toolkit
7.4 Edit System Settings
Now you have to define a few technical settings controlling the base functionality of the web client. In order to edit the System settings:
1. Open the Library Management and switch to the tab Component Settings. 2. Double-click the desired library to open the list of components available for
configuration. 3. Double-click Web Client, and then double-click System. 4. In the Base URL field, enter the URL where the web client can be reached
from other machines.
Example
You are configuring ADONIS NP 8.0. You are running the ADONIS NP web client on a machine with the IP 10.2.100.68. The URL should look like this:
"http://10.2.100.68:8000/ADONISNP8_0"
5. In the Technical Users field, select the technical user you created from the Available users list, i.e. “Technical_StandardRESTfulServices” (see Create Technical User in the Administration Toolkit).
6. Click OK.
7.5 Edit Settings for Standard RESTful Services
Now the Standard RESTful Services settings have to be adapted. In order to do so:
1. Open the Library Management and switch to the tab Component Settings. 2. Double-click the desired library to open the list of components available for
configuration. 3. Double-click Standard RESTful Services, and then double-click General. 4. Edit the settings in the Tokens tab and the Basic Auth tab.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 17/181
5. Click OK when you have completed the settings.
7.6 Standard RESTful Services – Tokens
The following settings are available in the Tokens tab:
Fig. 4: Example of settings in the Tokens tab
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 18/181
7.6.1 Rest Security Context
You can edit the default REST security context, or click the Add context button to generate a new REST security context. A security context consists of the following parts:
• key • secret • technical user • REST scenarios
Note: BOC Management Office RESTful services support multiple security contexts. At least one security context is required.
When would you want to use multiple security contexts? For example, you can configure one security context that allows for modification of users, and another one with access to the repository. You can execute requests with access rights of different technical users. During execution, you can choose which of the predefined security contexts should be used.
Key (for authentication by target system)
This parameter represents the name of the key which is used for communication with the web application using authenticated REST APIs. Enter a descriptive name, e.g. “boc.rest.key.mfb.StandardRESTfulServices”.
Secret (for authentication by target system)
This parameter represents the secret value of the key which is used for communication with the web application using authenticated REST APIs. Click the Generate secret button to generate the value of the key.
Technical user
From the Available Users list, select the technical user you created, i.e. “Technical_StandardRESTfulServices” (see Create Technical User in the Administration Toolkit).
REST Scenarios
In this area, you can enable specific REST scenarios. If a scenario is not enabled, all requests to its endpoints will return a 403 FORBIDDEN status. Also, HATEOAS links to endpoints which are disabled won't be returned in other endpoints. For example, if you disable the user write APIs scenario, a user response will contain a HATEOAS delete link, but a request to this link using the same security context would return the status code 403 FORBIDDEN. This link would be processed only when using a security context with the scenario enabled.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 19/181
The following REST scenarios are available:
• Repository Read APIs
Endpoints: repositories, statistics, model group, object group, model, object, modelling object, model/object/modelling object link, model image map, object usage, object relations, object relation endpoints, object relation endpoint details
• Repository Write APIs
Endpoints: repository objects, object group, object relations
• Repository Search APIs
Endpoints: search queries, search jobs
• User Read APIs
Endpoints: user group, roles, users
• User Write APIS
Endpoints: Users
7.6.2 Cache Path
This parameter is optional. Enter the absolute path to the directory in which cache files must be stored. The user under which the Apache Tomcat web server service is running must have write access to this directory.
Advantages of using this parameter:
• Model images (see section 9.5, with Accept:image/png) and model image maps (see section 9.9) are generated only once and then cached. Every time the model image or image map is requested, a check is performed if the model has changed. If there are no changes, the information is loaded from the file system. Otherwise, the cache is updated first. As a result, responses to these types of requests are faster and use fewer server resources.
• For search jobs (see section 11.2) the advantage is that created queries are saved in cache files and can be reused after a server restart. Without the cache path, queries are saved only in memory and are lost during restart.
7.7 Standard RESTful Services – Basic Auth
The following settings are available in the Basic Auth tab:
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 20/181
Fig. 5: Example of settings in the Basic auth tab
7.7.1 Enable Basic Authentication
Select this check box to enable basic authentication. All other options in this tab are inactive unless you select this check box.
If this check box is cleared, only token based authentication is possible.
Note: In addition to enabling basic authentication in the component settings, it must be enabled globally for the BOC Management Office product as well (see 7.9).
7.7.2 REST Scenarios
This area is identical in both the Tokens and Basic Auth tabs. Therefore, please refer to the corresponding description here.
7.8 Assign Web Module to all Users
Assign the following web module to all users so that the technical user can query the BOC Management Office product for data:
• Standard RESTful Services
In order to do so:
1. Open the Library Management and switch to the tab Component Settings. 2. Double-click the desired library to open the list of components available for
configuration. 3. Double-click Web Client, and then double-click Web Modules. 4. Activate the web module Standard RESTful Services for all users.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 21/181
Fig. 6: Assign Web Module to all Users
Done! Restart the Apache Tomcat web server and the application server. You can send send requests to the BOC Management Office product now.
7.9 Enable Basic Authentication for BOC Management Office Products
For security reasons, basic authentication is turned off by default in BOC Management Office products. If you want to use BOC Management Office RESTful services with basic authentication, you need to customize a configuration file. In order to do so:
1. Shut down Apache Tomcat (if it is running). 2. Open the folder <Tomcat installation>\webapps\<WAR file
name>\WEB-INF\registry\rest and edit the file RESTAuthorization.xml. Look for a section similar to:
<!--<entry key="REST_BASIC_AUTHENTICATION">true</entry>-->
3. Remove the comment characters (<!-- and -->). 4. Save the file and restart Apache Tomcat.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 22/181
8 REST Service The REST service is deployed as part of the web application hosted in a Java Web Container and is available at the URL http(s)://<ip-or-host-name>:<port>/<product>/rest/<api-version>.
Read API responses must be extended with HATEOAS links to related resources.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 23/181
9 Repository Read APIs
This section lists the repository read APIs available for the different resource types.
9.1 Repositories
Here is an API for retrieving a list of available repositories
HTTP Method GET URL path /rest/2.0/repos Request headers Accept: application/json and application/xml
Response A JSON document consisting of a list of available repositories
9.1.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root repos
2 Link to root model group of every repository
modelgroups repo modelgroups
3 Link to root object group of every repository
objectgroups repo objectgroups
4 Link to search of every repository
search repo search
5 Link to statistics of every repository
stats repo stats
9.1.2 Repositories Result Example
Here is a GET request to get a repositories list in an XML representation:
REQUEST GET rest/2.0/repos
Accept: application/xml
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 24/181
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos" method="GET" rel="self"/> </rest_links> <repos> <repo id="{e1138bdc-4063-490e-95f8-986d18c79ac3}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/root" method="GET" rel="modelgroups"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/root" method="GET" rel="objectgroups"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search" method="GET" rel="search"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/stats" method="GET" rel="stats"/> </rest_links> <name><![CDATA[Standard-Repository]]></name> </repo> ... </repos> </response>
Here is a GET request to get a repositories list in a JSON representation:
REQUEST GET rest/2.0/repos
Accept: application/json
RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos", "method": "GET", "rel": "self" } ], "repos": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/root", "method": "GET", "rel": "modelgroups" }, {
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 25/181
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/root", "method": "GET", "rel": "objectgroups" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search", "method": "GET", "rel": "search" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/stats", "method": "GET", "rel": "stats" } ], "id": "{e1138bdc-4063-490e-95f8-986d18c79ac3}", "name": "Standard-Repository" }, ... ] }
9.2 Statistics
An API for retrieving basic stats of a repository.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/stats Identifiers
{repo_id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... Request headers
Accept: application/json and application/xml
Response JSON/XML document consisting of basic statistic of a repository
9.2.1 HATEOAS Links
# Description rel Position in response Endpoint
1 Self link self root stats
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 26/181
9.2.2 Statistic Result Example
Here is a GET request that returns statistics of a repository in an XML representation:
REQUEST GET rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats
Accept: application/xml
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<stats models="74" objects="2776">
<rest_links>
<rest_link href="http://localhost/ADOxxWeb/rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats" method="GET" rel="self"/>
</rest_links>
</stats>
Here is a GET request that returns statistics of a repository in a JSON representation:
REQUEST GET rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats
Accept: application/json
RESPONSE {
"rest_links": [
{
"href": "http://localhost/ADOxxWeb/rest/2.0/repos/a9cb2ad3-a0fe-4bd8-a886-72b0581c2189/stats",
"method": "GET",
"rel": "self"
}
],
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 27/181
"models": 74,
"objects": 2776
}
9.3 Model Group
An API for retrieving a model group.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/modelgroups/{group-id}
/rest/2.0/repos/{repo_id}/modelgroups/{group-id}?icon=true&attribute={NAME_OF_ATTRIBUTE}&recursive=true Identifiers
{repo_id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {group-id} The ID of the group to be retrieved, root for the root model group. Request headers
Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Parameters
The parameters and flags are optional.
Parameters should be inserted after the question mark, after {group-id}
There are two types of parameters available for the model group API.
1) Boolean flag
icon If this flag is set to true, the icon for a model is returned.
recursive If this flag is set to true, the whole tree is returned, beginning from the model group whose ID was specified as the group ID and including models and specified attributes.
2) Attribute of models contained in queried groups
attribute={Name_of_attribute} The response will have the specified attribute for all models which are contained in the queried model groups, unless the attribute has no value or the model does not contain the attribute.
The attribute will not be returned if it is not a part of always loaded attributes and visible attributes.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 28/181
Only attributes that are marked as “always loaded” in the application library can be specified here.
The attributes can be configured in Administration Toolkit in the Metamodel Management -> Library View.
In 1) "LOADED_MODEL_ATTRIBUTES"
In 2) "VISIBLE_MODEL_ATTRIBUTES"
Response A JSON document consisting of ID, name, list of contained groups (ID and name), list of contained models (ID, type, name)
After the extension of the endpoint, the whole tree can be returned with contained models and subgroups
9.3.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self group modelgroups
2 Link to root object group of every repository
parent group modelgroups
3 Link to root model group of every repository
self model models
4 Self link parent model modelgroups
5 Link to every subgroup self subgroup modelgroups
9.3.2 Model Group Result Example
Here is a GET request that returns model group information in an XML representation:
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 29/181
REQUEST GET rest/2.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <locale>en</locale> <group id="{8815ee31-5d82-4b4e-89e2-0add7b846ea8}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e" method="GET" rel="parent"/> </rest_links> <name><![CDATA[Roadtrip example]]></name> <subgroups> <group id="{00ee28fb-496e-4034-9157-006d3539e52a}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a" method="GET" rel="self"/> </rest_links> <name><![CDATA[Organisation]]></name> </group> ... </subgroups> <models> <model id="{e0c87643-1925-4ec8-806a-be94d2e5ab3a}"> <name><![CDATA[HERE starts your roadtrip 1.00]]></name> <type><![CDATA[Company Map]]></type> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8" method="GET" rel="parent"/> </rest_links> </model> ... </models> </group> </response>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 30/181
Here is a GET request that returns model group information in a JSON representation:
REQUEST GET rest/2.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8
Accept: application/json
Accept-Language : en
RESPONSE { "locale": "en", "group": { "id": "{8815ee31-5d82-4b4e-89e2-0add7b846ea8}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e", "method": "GET", "rel": "parent" } ], "name": "Roadtrip example", "subgroups": [ { "id": "{00ee28fb-496e-4034-9157-006d3539e52a}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a", "method": "GET", "rel": "self" } ], "name": "Organisation" }, ... ], "models": [ { "id": "{e0c87643-1925-4ec8-806a-be94d2e5ab3a}", "name": "HERE starts your roadtrip 1.00", "type": "Company Map", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a", "method": "GET", "rel": "self" },
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 31/181
{ "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8", "method": "GET", "rel": "parent" } ] }, ... ] } }
Here is an XML response with additional parameters:
REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<response>
<locale>en</locale>
<group id="{8815ee31-5d82-4b4e-89e2-0add7b846ea8}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE" method="GET" rel="self"/>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e" method="GET" rel="parent"/>
</rest_links>
<name><![CDATA[Roadtrip example]]></name>
<subgroups>
<group id="{00ee28fb-496e-4034-9157-006d3539e52a}">
<rest_links>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 32/181
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a" method="GET" rel="self"/>
</rest_links>
<name><![CDATA[Organisation]]></name>
<subgroups/>
<models>
<model id="{a7e8862c-df3d-4003-8f05-119fc120a095}">
<name><![CDATA[Roadtrip - Organisation & Roles]]></name>
<type><![CDATA[Working Environment Model]]></type>
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B13e35228-5297-4724-91b5-3e2e40258ff6%7D.png" rel="icon"/>
<attributes>
<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_VERSION" attrType="STRING" xsi:type="string">
<name><![CDATA[Version]]></name>
<value/>
</attribute>
<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_STATE" attrType="ENUM" xsi:type="string">
<name><![CDATA[State]]></name>
<value><![CDATA[Released]]></value>
</attribute>
</attributes>
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/a7e8862c-df3d-4003-8f05-119fc120a095" method="GET" rel="self"/>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a" method="GET" rel="parent"/>
</rest_links>
</model>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 33/181
...
</models>
</group>
...
</subgroups>
<models>
<model id="{e0c87643-1925-4ec8-806a-be94d2e5ab3a}">
<name><![CDATA[HERE starts your roadtrip 1.00]]></name>
<type><![CDATA[Company Map]]></type>
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png" rel="icon"/>
<attributes>
<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_VERSION" attrType="STRING" xsi:type="string">
<name><![CDATA[Version]]></name>
<value><![CDATA[1.00]]></value>
</attribute>
<attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MFB_RWF_STATE" attrType="ENUM" xsi:type="string">
<name><![CDATA[State]]></name>
<value><![CDATA[Released]]></value>
</attribute>
</attributes>
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a" method="GET" rel="self"/>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8" method="GET" rel="parent"/>
</rest_links>
</model>
...
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 34/181
</models>
</group>
</response>
Here is a JSON response with additional parameters:
REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/modelgroups/00ee28fb-496e-4034-9157-006d3539e52a?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE
Accept: application/json
Accept-Language : en
RESPONSE {
"locale": "en",
"group": {
"id": "{8815ee31-5d82-4b4e-89e2-0add7b846ea8}",
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8?recursive=true&icon=true&attribute=MFB_RWF_VERSION&attribute=MFB_RWF_STATE",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e",
"method": "GET",
"rel": "parent"
}
],
"name": "Roadtrip example",
"subgroups": [
{
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 35/181
"id": "{93380d01-64d1-4a75-bebd-35cc259d87c0}",
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/93380d01-64d1-4a75-bebd-35cc259d87c0",
"method": "GET",
"rel": "self"
}
],
"name": "Process flows",
"subgroups": [
{
"id": "{3a0513b9-84b1-4e50-9ec5-c7b2f320fcc0}",
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3a0513b9-84b1-4e50-9ec5-c7b2f320fcc0",
"method": "GET",
"rel": "self"
}
],
"name": "Support processes",
"subgroups": [],
"models": [
{
"id": "{0d638c2a-ad77-4e63-8cd2-36edc594fa95}",
"name": "Make preparations for travel 1.00",
"type": "Business Process Diagram",
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Baee098ea-071d-4150-8ce9-011eaf93643f%7D.png",
"rel": "icon"
},
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 36/181
"attributes": [
{
"name": "Version",
"metaName": "MFB_RWF_VERSION",
"attrType": "STRING",
"value": "1.00"
},
{
"name": "State",
"metaName": "MFB_RWF_STATE",
"attrType": "ENUM",
"value": "Released"
}
],
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/0d638c2a-ad77-4e63-8cd2-36edc594fa95",
"rel": "self",
"type": "GET"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/3a0513b9-84b1-4e50-9ec5-c7b2f320fcc0",
"rel": "parent",
"type": "GET"
}
]
},
...
]
},
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 37/181
...
],
"models": []
},
{
"id": "{c036c85a-2b09-4c62-9169-1da992df71a8}",
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/c036c85a-2b09-4c62-9169-1da992df71a8",
"method": "GET",
"rel": "self"
}
],
"name": "Governance, Risk and Compliance",
"subgroups": [],
"models": [
{
"id": "{d7ff6821-84a9-4070-9f07-a932f8bcb8e9}",
"name": "Roadtrip - Risks and Control (Objectives)",
"type": "Analysis Model",
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B472156d3-9f20-4c4c-af23-a23825bc0815%7D.png",
"rel": "icon"
},
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/d7ff6821-84a9-4070-9f07-a932f8bcb8e9",
"method": "GET",
"rel": "self"
},
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 38/181
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/c036c85a-2b09-4c62-9169-1da992df71a8",
"method": "GET",
"rel": "parent"
}
]
}
]
},
...
],
"models": [
{
"id": "{e0c87643-1925-4ec8-806a-be94d2e5ab3a}",
"name": "HERE starts your roadtrip 1.00",
"type": "Company Map",
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png",
"rel": "icon"
},
"attributes": [
{
"name": "Version",
"metaName": "MFB_RWF_VERSION",
"attrType": "STRING",
"value": "1.00"
},
{
"name": "State",
"metaName": "MFB_RWF_STATE",
"attrType": "ENUM",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 39/181
"value": "Released"
}
],
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/models/e0c87643-1925-4ec8-806a-be94d2e5ab3a",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/modelgroups/8815ee31-5d82-4b4e-89e2-0add7b846ea8",
"method": "GET",
"rel": "parent"
}
]
},
...
]
}
}
9.4 Object Group
An API for retrieving an object group.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objectgroups/{group-id}
/rest/2.0/repos/{repo_id}/objectgroups/{group-id}?icon=true&recursive=true Identifiers
{repo_id} The ID of a repository that is used to perform the request. The Value must not contain brackets. E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...
{group-id} The ID of the group to be retrieved, root for the root object group. Request headers
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 40/181
Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Parameters
The parameters and flags are optional.
Parameters should be inserted after the question mark, after {group-id}.
There are two Boolean flags: icon If flag is set to true the icon for an object is returned
recursive If this flag is set to true, the whole tree is returned, beginning from the model group whose ID was specified as group ID and including models and specified attributes.
Response A JSON document consisting of ID, name, list of contained groups (ID and name), list of contained objects (ID, type, name)
9.4.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self group objectgroups
2 Link to root object group of every repository
parent group objectgroups
3 Link to root model group of every repository
self object objects
4 Self link parent object objectgroups
5 Link to every subgroup self subgroup objectgroups
9.4.2 Object Group Result Example
Here is a GET request that returns object group information in an XML representation:
REQUEST GET rest/2.0/repos/e1c24623-3ece-494f-949c-135673cad8d9/objectgroups/4b49163b-4cb5-452a-9a42-62ef359613f4
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 41/181
Content-Length: ... <response> <locale>en</locale> <group id="{3c944389-eb3d-438e-a2d8-7b1c7513144c}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6" method="GET" rel="parent"/> </rest_links> <name><![CDATA[02 CP Core Processes]]></name> <subgroups> <group id="{727abead-5e88-4f5b-b134-6727df15c4f7}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7" method="GET" rel="self"/> </rest_links> <name><![CDATA[CP.01 Advise Customer]]></name> </group> ... </subgroups> <objects> <object id="{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}"> <name><![CDATA[CP.05 Investment Security Transactions]]></name> <class><![CDATA[Process]]></class> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c" method="GET" rel="parent"/> </rest_links> </object> ... </objects> </group> </response>
Here is a GET request that returns object group information in a JSON representation:
REQUEST GET rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c
Accept: application/json
Accept-Language : en
RESPONSE
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 42/181
{ "locale": "en", "group": { "id": "{3c944389-eb3d-438e-a2d8-7b1c7513144c}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6", "method": "GET", "rel": "parent" } ], "name": "02 CP Core Processes", "subgroups": [ { "id": "{727abead-5e88-4f5b-b134-6727df15c4f7}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7", "method": "GET", "rel": "self" } ], "name": "CP.01 Advise Customer" }, ... ], "objects": [ { "id": "{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}", "name": "CP.05 Investment Security Transactions", "class": "Process", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c", "method": "GET", "rel": "parent" } ] }, ... ] } }
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 43/181
An XML representation with Boolean flags added:
REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/objectgroups/7e749f24-7a20-41e2-b3b2-132fd0d98392?icon=true&recursive=true
Accept: application/xml
Accept-Language : en
RESPONSE <response>
<locale>en</locale>
<group id="{3c944389-eb3d-438e-a2d8-7b1c7513144c}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c?icon=true&recursive=true" method="GET" rel="self"/>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6" method="GET" rel="parent"/>
</rest_links>
<name><![CDATA[02 CP Core Processes]]></name>
<subgroups>
<group id="{727abead-5e88-4f5b-b134-6727df15c4f7}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7" method="GET" rel="self"/>
</rest_links>
<name><![CDATA[CP.01 Advise Customer]]></name>
<subgroups/>
<objects>
<object id="{50eeb619-a61a-49cf-b7d0-b36b3c3f8a37}">
<name><![CDATA[CP.01.02 Prepare and conduct consultation for Business Customers (BC)]]></name>
<class><![CDATA[Process]]></class>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 44/181
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png" rel="icon"/>
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/50eeb619-a61a-49cf-b7d0-b36b3c3f8a37" method="GET" rel="self"/>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7" method="GET" rel="parent"/>
</rest_links>
</object>
...
</objects>
</group>
...
</subgroups>
<objects>
<object id="{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}">
<name><![CDATA[CP.05 Investment Security Transactions]]></name>
<class><![CDATA[Process]]></class>
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png" rel="icon"/>
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e" method="GET" rel="self"/>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c" method="GET" rel="parent"/>
</rest_links>
</object>
...
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 45/181
</objects>
</group>
</response>
A JSON representation with Boolean flags added:
REQUEST GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/objectgroups/7e749f24-7a20-41e2-b3b2-132fd0d98392?icon=true&recursive=true
Accept: application/json
Accept-Language : en
RESPONSE { "locale": "en", "group": { "id": "{3c944389-eb3d-438e-a2d8-7b1c7513144c}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c?icon=true&recursive=true", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/09d41ec2-fdf5-4426-bb01-835a2dac97b6", "method": "GET", "rel": "parent" } ], "name": "02 CP Core Processes", "subgroups": [ { "id": "{727abead-5e88-4f5b-b134-6727df15c4f7}",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 46/181
"rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7", "method": "GET", "rel": "self" } ], "name": "CP.01 Advise Customer", "subgroups": [], "objects": [ { "id": "{50eeb619-a61a-49cf-b7d0-b36b3c3f8a37}", "name": "CP.01.02 Prepare and conduct consultation for Business Customers (BC)", "class": "Process", "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png", "rel": "icon" }, "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/50eeb619-a61a-49cf-b7d0-b36b3c3f8a37", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/727abead-5e88-4f5b-b134-6727df15c4f7", "method": "GET", "rel": "parent" }
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 47/181
] }, ... ] }, ... ], "objects": [ { "id": "{1c2c8c45-f7f5-4779-9813-5d3dba117a8e}", "name": "CP.05 Investment Security Transactions", "class": "Process", "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bfec6d1d3-e52b-4eb4-a2f9-4e29b7746ec2%7D.png", "rel": "icon" }, "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/1c2c8c45-f7f5-4779-9813-5d3dba117a8e", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objectgroups/3c944389-eb3d-438e-a2d8-7b1c7513144c", "method": "GET", "rel": "parent" } ] }, ...
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 48/181
] } }
9.5 Model
An API for retrieving model properties or images.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/models/{model-id}?dpi={dpi}&attribute={attribute}&relation={relation}&embeddedFonts={embeddedFonts}&showAll={showAll} Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {model-id} The ID of the model to be retrieved. The value must not contain brackets.
{dpi}
Optional. Defines the DPIs in which the image is generated. 300 by default. This parameter is relevant if the request header Accept had the value image/png.
Cached DPIs: 300, 150 and 72, images for any other value are generated at runtime.
Note: DPI should not be smaller or equal to zero.
{attribute}
Optional, defines the attributes of the model that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the model are returned.
E.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION
{relation}
Optional, defines the relation of the model that may be returned in result. There can be many of them within a one request URL. If no relation parameter is defined then all relations of model are returned.
E.g. &relation=CUSTOM_RELATION&relation=RC_MANAGER {embeddedFonts}
Optional. Defines whether fonts should be embedded or not. False by default. This parameter is relevant for the header: Accept: image/svg+xml.
{showAll} Optional, if set to true returns all attributes and relations else only these visible in notebook. False by default.
Request headers Accept: application/json, application/xml, image/png and image/svg+xml
Accept-Language: ISO 639-1 language code
Response
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 49/181
A JSON or XML document consisting of ID, type, name, list of properties (name, value), list of objects (ID, class, name).
A PNG image if the request header Accept had the value image/png.
An SVG image if the request header Accept had the value image/svg+xml
9.5.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self item models
2 Link to modelgroup with this model
parent item modelgroups
3 Link to the notebook (properties view)
notebookLink item link
4 Link to imagemap imageMap item imagemap
5 Link to each relation target
self target models/objects/modeling objects
6 Link to each contained object
self object modeling objects
9.5.2 Model Result Example
Here is a GET request that returns model information in an XML representation:
REQUEST GET rest/2.0/repos/bbb44e57-ab8e-451e-b89d-1c193e5ee2dd/models/6ae1d61c-f5da-4957-828c-8b7c61297ae6
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 50/181
<locale>en</locale>
<item id="{09529521-202c-4fb7-b512-72edd299f339}" artefactType="DIAGRAM" metaName="MT_COMPANY_MAP">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/link" method="GET" rel="notebookLink" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e" method="GET" rel="parent" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/imagemap" method="GET" rel="imageMap" />
</rest_links>
<name>
<![CDATA[companymap]]>
</name>
<type>
<![CDATA[Company Map]]>
</type>
<link href="http://localhost:8080/ADOxxWeb?t=view&at=1&classId=14a6bed2-071f-42af-afc7-9b00e6ae97a2&libObjID=14a6bed2-071f-42af-afc7-9b00e6ae97a2&vt=graphical&id=09529521-202c-4fb7-b512-72edd299f339" />
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png" rel="icon" />
<attributes>
<attribute metaName="A_DESCRIPTION" attrType="STRING" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">
<name>
<![CDATA[Description]]>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 51/181
</name>
<value></value>
</attribute>
...
</attributes>
<relations>
<relation metaName="RC_OWNER" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">
<name>
<![CDATA[Process owner]]>
</name>
<targets />
</relation>
<relation metaName="SCOPE" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">
<name>
<![CDATA[Scope]]>
</name>
<targets>
<target id="{f16bb57e-4402-4339-9242-7ee98e492149}" metaName="C_ORGANIZATIONAL_UNIT" direction="OUTGOING">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/f16bb57e-4402-4339-9242-7ee98e492149" method="GET" rel="self" />
</rest_links>
<name>
<![CDATA[Accounting/ balance sheet/ taxes]]>
</name>
<type>
<![CDATA[Organisational Unit]]>
</type>
<link href="http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=26efd4bb-19a5-47f1-939f-520283f3c342&libObjID=26efd4bb-19a5-47f1-939f-
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 52/181
520283f3c342&id=f16bb57e-4402-4339-9242-7ee98e492149&rid=f16bb57e-4402-4339-9242-7ee98e492149" />
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B26efd4bb-19a5-47f1-939f-520283f3c342%7D.png" rel="icon" />
</target>
</targets>
</relation>
...
</relations>
<objects>
<object id="{9624da5e-3265-4ea5-aae5-2c01f3bb95cb}" metaName="C_PROCESS">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/objects/9624da5e-3265-4ea5-aae5-2c01f3bb95cb" method="GET" rel="self" />
</rest_links>
<name>
<![CDATA[Process-d736d0fb]]>
</name>
<type>
<![CDATA[Process]]>
</type>
</object>
...
</objects>
</item>
</response>
Here is a GET request that returns model information in a JSON representation:
REQUEST GET rest/2.0/repos/bbb44e57-ab8e-451e-b89d-1c193e5ee2dd/models/6ae1d61c-f5da-4957-828c-8b7c61297ae6
Accept: application/json
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 53/181
Accept-Language : en
RESPONSE {
"locale": "en",
"item": {
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/link",
"method": "GET",
"rel": "notebookLink"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/modelgroups/3b7034d4-a336-4ed5-bef2-363d7a48c55e",
"method": "GET",
"rel": "parent"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/imagemap",
"method": "GET",
"rel": "imageMap"
}
],
"id": "{09529521-202c-4fb7-b512-72edd299f339}",
"name": "companymap",
"type": "Company Map",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 54/181
"artefactType": "DIAGRAM",
"metaName": "MT_COMPANY_MAP",
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=view&at=1&classId=14a6bed2-071f-42af-afc7-9b00e6ae97a2&libObjID=14a6bed2-071f-42af-afc7-9b00e6ae97a2&vt=graphical&id=09529521-202c-4fb7-b512-72edd299f339"
},
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B14a6bed2-071f-42af-afc7-9b00e6ae97a2%7D.png",
"rel": "icon"
},
"attributes": [
{
"name": "Description",
"metaName": "A_DESCRIPTION",
"attrType": "STRING",
"value": ""
},
...
],
"relations": [
{
"name": "Process owner",
"metaName": "RC_OWNER",
"targets": []
},
{
"name": "Scope",
"metaName": "SCOPE",
"targets": [
{
"rest_links": [
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 55/181
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/f16bb57e-4402-4339-9242-7ee98e492149",
"method": "GET",
"rel": "self"
}
],
"id": "{f16bb57e-4402-4339-9242-7ee98e492149}",
"name": "Accounting/ balance sheet/ taxes",
"type": "Organisational Unit",
"metaName": "C_ORGANIZATIONAL_UNIT",
"direction": "OUTGOING",
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=26efd4bb-19a5-47f1-939f-520283f3c342&libObjID=26efd4bb-19a5-47f1-939f-520283f3c342&id=f16bb57e-4402-4339-9242-7ee98e492149&rid=f16bb57e-4402-4339-9242-7ee98e492149"
},
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B26efd4bb-19a5-47f1-939f-520283f3c342%7D.png",
"rel": "icon"
}
}
]
},
...
],
"objects": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 56/181
afab5dd9eb8e/models/09529521-202c-4fb7-b512-72edd299f339/objects/9624da5e-3265-4ea5-aae5-2c01f3bb95cb",
"method": "GET",
"rel": "self"
}
],
"id": "{9624da5e-3265-4ea5-aae5-2c01f3bb95cb}",
"name": "Process-d736d0fb",
"type": "Process",
"metaName": "C_PROCESS"
},
...
]
}
}
9.6 Object
An API for retrieving object properties.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object-id}?attribute={attribute}&relation={relation}&showAll={showAll} Identifiers
{repo_id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {object-id} The ID of the object to be retrieved.
{attribute}
Optional, defines the attributes of the object that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the object are returned.
E.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION
{relation}
Optional, defines the relation of the object that may be returned in result. There can be many of them within a one request URL. If no relation parameter is defined then all relations of object are returned.
E.g. &relation=CUSTOM_RELATION&relation=RC_MANAGER
{showAll} Optional, if set to true returns all attributes and relations else only these visible in notebook. False by default.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 57/181
Request headers
Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response JSON/XML document consisting of ID, class, name, list of properties (name, value)
9.6.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self item objects
2 Link to object group with this object
parent item objectgroups
3 Link to the notebook (properties view)
notebookLink item link
4 Link to object usage
usage item usage
5 Link to list of available incoming relations
incomingRelations item relations/incoming
6 Link to list of available outgoing relations
outgoingRelations item relations/outgoing
7 Link to each relation target
self target models/objects/modeling objects
9.6.2 Object Result Example
Here is a GET request that returns object information in an XML representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 58/181
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<locale>en</locale>
<item id="{059f3022-eb66-4080-a980-cd6d5fed1da9}" artefactType="REPOSITORY_OBJECT" metaName="C_PRODUCT">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/link" method="GET" rel="notebookLink" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage" method="GET" rel="usage" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objectgroups/4b49163b-4cb5-452a-9a42-62ef359613f4" method="GET" rel="parent" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/incoming" method="GET" rel="incomingRelations" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/outgoing" method="GET" rel="outgoingRelations" />
</rest_links>
<name>
<![CDATA[product]]>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 59/181
</name>
<type>
<![CDATA[Product]]>
</type>
<link href="http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=198fcc2f-bf30-4b9a-85ca-153aee3a7891&libObjID=198fcc2f-bf30-4b9a-85ca-153aee3a7891&id=059f3022-eb66-4080-a980-cd6d5fed1da9&rid=059f3022-eb66-4080-a980-cd6d5fed1da9" />
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B198fcc2f-bf30-4b9a-85ca-153aee3a7891%7D.png" rel="icon" />
<attributes>
<attribute metaName="A_DESCRIPTION" attrType="STRING" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">
<name>
<![CDATA[Description]]>
</name>
<value></value>
</attribute>
...
</attributes>
<relations>
<relation metaName="RC_RESPONSIBLE_PERSON_DEPUTY" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">
<name>
<![CDATA[Responsible person (deputy)]]>
</name>
<targets />
</relation>
<relation metaName="RC_IS_APPLICATION_OWNER" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">
<name>
<![CDATA[Responsible person]]>
</name>
<targets>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 60/181
<target id="{04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d}" metaName="USER" direction="OUTGOING">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d" method="GET" rel="self" />
</rest_links>
<name>
<![CDATA[user2]]>
</name>
<type>
<![CDATA[User]]>
</type>
<link href="http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=0127098d-50f0-4d0e-a054-c19de9bc9b0a&libObjID=0127098d-50f0-4d0e-a054-c19de9bc9b0a&id=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d&rid=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d" />
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B0127098d-50f0-4d0e-a054-c19de9bc9b0a%7D.png" rel="icon" />
</target>
</targets>
</relation>
...
</relations>
</item>
</response>
Here is a GET request that returns object information in a JSON representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9
Accept: application/json
Accept-Language : en
RESPONSE
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 61/181
{
"locale": "en",
"item": {
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/link",
"method": "GET",
"rel": "notebookLink"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage",
"method": "GET",
"rel": "usage"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objectgroups/4b49163b-4cb5-452a-9a42-62ef359613f4",
"method": "GET",
"rel": "parent"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/incoming",
"method": "GET",
"rel": "incomingRelations"
},
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 62/181
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/relations/outgoing",
"method": "GET",
"rel": "outgoingRelations"
}
],
"id": "{059f3022-eb66-4080-a980-cd6d5fed1da9}",
"name": "product",
"type": "Product",
"artefactType": "REPOSITORY_OBJECT",
"metaName": "C_PRODUCT",
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=198fcc2f-bf30-4b9a-85ca-153aee3a7891&libObjID=198fcc2f-bf30-4b9a-85ca-153aee3a7891&id=059f3022-eb66-4080-a980-cd6d5fed1da9&rid=059f3022-eb66-4080-a980-cd6d5fed1da9"
},
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B198fcc2f-bf30-4b9a-85ca-153aee3a7891%7D.png",
"rel": "icon"
},
"attributes": [
{
"name": "Description",
"metaName": "A_DESCRIPTION",
"attrType": "STRING",
"value": ""
},
...
],
"relations": [
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 63/181
{
"name": "Responsible person (deputy)",
"metaName": "RC_RESPONSIBLE_PERSON_DEPUTY",
"targets": []
},
{
"name": "Responsible person",
"metaName": "RC_IS_APPLICATION_OWNER",
"targets": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d",
"method": "GET",
"rel": "self"
}
],
"id": "{04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d}",
"name": "user2",
"type": "User",
"metaName": "USER",
"direction": "OUTGOING",
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=nb&at=0&classId=0127098d-50f0-4d0e-a054-c19de9bc9b0a&libObjID=0127098d-50f0-4d0e-a054-c19de9bc9b0a&id=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d&rid=04eabf24-ad6a-4e77-9b2c-dca0ac0c1e3d"
},
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B0127098d-50f0-4d0e-a054-c19de9bc9b0a%7D.png",
"rel": "icon"
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 64/181
}
}
]
},
...
]
}
}
9.7 Modelling Object
An API for retrieving modelling object properties.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/models/{model-id}/objects/{object-id}?attribute={attribute}&relation={relation}&showAll={showAll} Identifiers
{repo-id} ID of repository that is used to perform the request. Value must not contain brackets.
E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {model-id} ID of the model to be retrieved. Value must not contain brackets. {object-id} ID of the modelling object to be retrieved
{attribute}
Optional, defines the attributes of the modelling object that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the modelling object are returned.
E.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION
{relation}
Optional, defines the relation of the modeling object that may be returned in result. There can be many of them within a one request URL. If no relation parameter is defined then all relations of modeling object are returned.
E.g. &relation=CUSTOM_RELATION&relation=RC_MANAGER
{showAll} Optional, if set to true returns all attributes and relations else only these visible in notebook. False by default.
Request headers Accept: application/json
Accept-Language: ISO 639-1 language code
Response JSON/XML document consisting of ID, class, name, list of properties (name, value)
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 65/181
9.7.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self item modeling objects
2 Link to model parent item models
3 Link to repository object
repositoryObject item objects
4 Link to the notebook
notebookLink item link
5 Link to each reation target
self target models/objects/modeling objects
9.7.2 Modelling Object Result Example
Here is a GET request that returns modelling object information in an XML representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<locale>en</locale>
<item id="{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}" artefactType="MODINST" metaName="C_SUB_PROCESS" repositoryObjectId="{691cfc46-a725-4908-9078-5c0b1cd9e98f}" modelId="{f3f94bf5-25f7-4510-9744-4dbe60c10611}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 66/181
afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd?showAll=true" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd/link" method="GET" rel="notebookLink" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611" method="GET" rel="parent" />
</rest_links>
<name>
<![CDATA[Subprocess]]>
</name>
<type>
<![CDATA[Subprocess]]>
</type>
<link href="http://localhost:8080/ADOxxWeb?t=view&at=6&classId=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&libObjID=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&vt=graphical&id=ad26cfc2-6910-4567-9c75-d1d51bd6b1cd&mid=f3f94bf5-25f7-4510-9744-4dbe60c10611" />
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bd9c71c3d-1d9f-435b-9a3b-b240549dfd5a%7D.png" rel="icon" />
<attributes>
<attribute metaName="IDENTIFICATION_OF_CHANGES" attrType="ENUM" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">
<name>
<![CDATA[Identification of changes]]>
</name>
<value>
<![CDATA[No change]]>
</value>
</attribute>
...
</attributes>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 67/181
<relations>
<relation metaName="RC_OWNS" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">
<name>
<![CDATA[Owns]]>
</name>
<targets />
</relation>
<relation metaName="RC_REFERENCED_EVENT_ONE" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="reference">
<name>
<![CDATA[Referenced event (behaviour = one)]]>
</name>
<targets>
<target id="{d829b111-24b9-4609-be1e-24d4478927aa}" metaName="C_END_EVENT" direction="OUTGOING">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/a5791dfd-04db-45ae-bebd-d1011b779de3/objects/d829b111-24b9-4609-be1e-24d4478927aa" method="GET" rel="self" />
</rest_links>
<name>
<![CDATA[Relación de negocio terminada]]>
</name>
<type>
<![CDATA[End Event]]>
</type>
<link href="http://localhost:8080/ADOxxWeb?t=view&at=6&classId=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&libObjID=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&vt=graphical&id=d829b111-24b9-4609-be1e-24d4478927aa&mid=a5791dfd-04db-45ae-bebd-d1011b779de3" />
<icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Beb70fe51-7f1e-428f-9d5a-2fd15d318ee6%7D.png" rel="icon" />
</target>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 68/181
</targets>
</relation>
...
</relations>
</item>
</response>
Here is a GET request that returns modelling object information in a JSON representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd
Accept: application/json
Accept-Language : en
RESPONSE {
"locale": "en",
"item": {
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd/link",
"method": "GET",
"rel": "notebookLink"
},
{
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 69/181
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611",
"method": "GET",
"rel": "parent"
}
],
"id": "{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}",
"name": "Subprocess",
"type": "Subprocess",
"artefactType": "MODINST",
"metaName": "C_SUB_PROCESS",
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=view&at=6&classId=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&libObjID=d9c71c3d-1d9f-435b-9a3b-b240549dfd5a&vt=graphical&id=ad26cfc2-6910-4567-9c75-d1d51bd6b1cd&mid=f3f94bf5-25f7-4510-9744-4dbe60c10611"
},
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Bd9c71c3d-1d9f-435b-9a3b-b240549dfd5a%7D.png",
"rel": "icon"
},
"attributes": [
{
"name": "Identification of changes",
"metaName": "IDENTIFICATION_OF_CHANGES",
"attrType": "ENUM",
"value": "No change"
},
...
],
"relations": [
{
"name": "Referenced event (behaviour = one)",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 70/181
"metaName": "RC_REFERENCED_EVENT_ONE",
"targets": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/a5791dfd-04db-45ae-bebd-d1011b779de3/objects/d829b111-24b9-4609-be1e-24d4478927aa",
"method": "GET",
"rel": "self"
}
],
"id": "{d829b111-24b9-4609-be1e-24d4478927aa}",
"name": "Relación de negocio terminada",
"type": "End Event",
"metaName": "C_END_EVENT",
"direction": "OUTGOING",
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=view&at=6&classId=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&libObjID=eb70fe51-7f1e-428f-9d5a-2fd15d318ee6&vt=graphical&id=d829b111-24b9-4609-be1e-24d4478927aa&mid=a5791dfd-04db-45ae-bebd-d1011b779de3"
},
"icon": {
"href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Beb70fe51-7f1e-428f-9d5a-2fd15d318ee6%7D.png",
"rel": "icon"
}
}
]
},
{
"name": "Referenced aggregation",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 71/181
"metaName": "RC_REFERENCED_AGGREGATION_M",
"targets": []
},
...
],
"repositoryObjectId": "{691cfc46-a725-4908-9078-5c0b1cd9e98f}",
"modelId": "{f3f94bf5-25f7-4510-9744-4dbe60c10611}"
}
}
9.8 Model/Object/Modelling Object Link
An API for retrieving the URL of a model or object or modelling object.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/models/{model-id}/link
/rest/2.0/repos/{repo_id}/objects/{object-id}/link
/rest/2.0/repos/{repo_id}/models/{model-id}/objects/{object-id}/link Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...
{model-id} The ID of the model whose URL is to be retrieved. The value must not contain brackets.
{object-id} The ID of the object whose URL is to be retrieved. Request headers Accept: application/json and application/xml
Response A JSON or XML document consisting of the URL of a specific model or object.
9.8.1 HATEOAS Links
# Description rel Position in response
Endpoint
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 72/181
1 Self link self item link
2 Link to parent
parent item models/objects/modeling objects
9.8.2 URL Result Example
Here is a GET request that returns a model URL in an XML representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link
Accept: application/xml
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<item>
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611" method="GET" rel="parent" />
</rest_links>
<link href="http://localhost:8080/ADOxxWeb?t=view&at=1&classId=aee098ea-071d-4150-8ce9-011eaf93643f&libObjID=aee098ea-071d-4150-8ce9-011eaf93643f&vt=graphical&id=f3f94bf5-25f7-4510-9744-4dbe60c10611" />
</item>
</response>
Here is a GET request that returns a model URL in a JSON representation:
REQUEST
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 73/181
GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link
Accept: application/json
RESPONSE {
"item": {
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/link",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611",
"method": "GET",
"rel": "parent"
}
],
"link": {
"href": "http://localhost:8080/ADOxxWeb?t=view&at=1&classId=aee098ea-071d-4150-8ce9-011eaf93643f&libObjID=aee098ea-071d-4150-8ce9-011eaf93643f&vt=graphical&id=f3f94bf5-25f7-4510-9744-4dbe60c10611"
}
}
}
9.9 Model Image Map
An API for retrieving the image map of a model. An image map consists of the coordinates behind the graphic representation of the model. You can find out exactly where objects lie and what size they have.
HTTP Method GET URL path
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 74/181
/rest/2.0/repos/{repo_id}/models/{model-id}/imagemap?dpi={dpi} Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...
{model-id} The ID of the model whose imagemap is to be retrieved. The value must not contain brackets.
{dpi}
Optional, defines the DPIs in which the image is generated. 300 by default.
Cached DPIs: 300, 150 and 72, images for any other value are generated at runtime.
Note: DPI should not be smaller or equal to zero. Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document consisting of information about the model (ID, model, class ID, time of change, image - base64 encoded string) and list of contained modelling objects.
9.9.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self item imagemap
2 Link to model parent item models
3 Self link to every model instance
self modelInstance modeling objects
4 Link to repository object of every model instance
repositoryObject modelInstance objects
9.9.2 Image Map Result Example
Here is a GET request that returns a model image map in an XML representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap
Accept: application/xml
Accept-Language : en
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 75/181
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<model id="{f3f94bf5-25f7-4510-9744-4dbe60c10611}" type="MODEL" classId="{aee098ea-071d-4150-8ce9-011eaf93643f}" changeTime="1548842838183">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611" method="GET" rel="parent" />
</rest_links>
<name>
<![CDATA[modelo]]>
</name>
<posInfo width="6455" height="3784" x="0" y="0" />
<modelInstances>
<modelInstances id="{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}" type="INSTANCE" classId="{d9c71c3d-1d9f-435b-9a3b-b240549dfd5a}" repositoryObjectId="{691cfc46-a725-4908-9078-5c0b1cd9e98f}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/691cfc46-a725-4908-9078-5c0b1cd9e98f" method="GET" rel="repositoryObject" />
</rest_links>
<name>
<![CDATA[Subprocess]]>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 76/181
</name>
<posInfo width="634" height="321" x="1976" y="946" />
</modelInstances>
...
</modelInstances>
<image><![CDATA[iVBORw0KGgoAAAANSUhEUgAAFucAAA4+CAIAAABJ2+5FAAAACXBIW...]]></image>
</model>
</response>
Here is a GET request that returns a model image map in a JSON representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap
Accept: application/json
Accept-Language : en
RESPONSE {
"item": {
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/imagemap",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611",
"method": "GET",
"rel": "parent"
}
],
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 77/181
"id": "{f3f94bf5-25f7-4510-9744-4dbe60c10611}",
"name": "modelo",
"type": "MODEL",
"classId": "{aee098ea-071d-4150-8ce9-011eaf93643f}",
"width": 6455,
"height": 3784,
"x": 0,
"y": 0,
"modelInstances": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/f3f94bf5-25f7-4510-9744-4dbe60c10611/objects/ad26cfc2-6910-4567-9c75-d1d51bd6b1cd",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/691cfc46-a725-4908-9078-5c0b1cd9e98f",
"method": "GET",
"rel": "repositoryObject"
}
],
"id": "{ad26cfc2-6910-4567-9c75-d1d51bd6b1cd}",
"name": "Subprocess",
"type": "INSTANCE",
"classId": "{d9c71c3d-1d9f-435b-9a3b-b240549dfd5a}",
"repositoryObjectId": "{691cfc46-a725-4908-9078-5c0b1cd9e98f}",
"width": 634,
"height": 321,
"x": 1976,
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 78/181
"y": 946
}
],
"changeTime": 1548842838183,
"image": "iVBORw0KGgoAAAANSUhEUgAAFucAAA4+CAIAAABJ2+5FAAAACXBIW..."
}
}
9.10 Object Usage
An API for retrieving modelling instances of a repository object.
Note: Object usage is based on search which means that results may be slightly out of date if they were recently changed. There may be a delay of up to 30 seconds.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object-id}/usage Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...
{object-id} The ID of the object whose modelling instances are to be retrieved. The value must not contain brackets.
Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document with the total number of hits and a non-null array with result items. Each result item consists of information about the object (id, name, type, etc.).
9.10.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root usage
2 Link to repository object parent root objects
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 79/181
3 Link to every object usage self item objects
4 Link to parent model of every object usage
parent item models
9.10.2 Object Usage Result Example
Here is a GET request that returns object usage information in an XML representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9" method="GET" rel="parent" />
</rest_links>
<hitsTotal>6</hitsTotal>
<locale>en</locale>
<items>
<item id="{11055484-7d95-4545-8c16-0708f2b2af8f}" artefactType="MODINST" metaName="C_PRODUCT">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0/objects/11055484-7d95-4545-8c16-0708f2b2af8f" method="GET" rel="self" />
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 80/181
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0" method="GET" rel="parent" />
</rest_links>
<name>
<![CDATA[product]]>
</name>
<type>
<![CDATA[Product]]>
</type>
<modelId>
<![CDATA[{c2c01210-d767-46ec-ac40-0cfd3d0088b0}]]>
</modelId>
</item>
<item id="{19529281-834e-4ef4-99cc-02b7e5fa34b9}" artefactType="MODINST" metaName="C_PRODUCT">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7/objects/19529281-834e-4ef4-99cc-02b7e5fa34b9" method="GET" rel="self" />
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7" method="GET" rel="parent" />
</rest_links>
<name>
<![CDATA[product]]>
</name>
<type>
<![CDATA[Product]]>
</type>
<modelId>
<![CDATA[{c7715a8e-6487-4a8b-8ab2-9d34b00c41c7}]]>
</modelId>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 81/181
</item>
...
</items>
</response>
Here is a GET request that returns object usage information in a JSON representation:
REQUEST GET rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage
Accept: application/json
Accept-Language : en
RESPONSE {
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9/usage",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/objects/059f3022-eb66-4080-a980-cd6d5fed1da9",
"method": "GET",
"rel": "parent"
}
],
"hitsTotal": 6,
"locale": "en",
"items": [
{
"rest_links": [
{
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 82/181
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0/objects/11055484-7d95-4545-8c16-0708f2b2af8f",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c2c01210-d767-46ec-ac40-0cfd3d0088b0",
"method": "GET",
"rel": "parent"
}
],
"id": "{11055484-7d95-4545-8c16-0708f2b2af8f}",
"name": "product",
"type": "Product",
"artefactType": "MODINST",
"metaName": "C_PRODUCT",
"modelId": "{c2c01210-d767-46ec-ac40-0cfd3d0088b0}"
},
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7/objects/19529281-834e-4ef4-99cc-02b7e5fa34b9",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/bb867572-ab34-4ae1-a411-afab5dd9eb8e/models/c7715a8e-6487-4a8b-8ab2-9d34b00c41c7",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 83/181
"method": "GET",
"rel": "parent"
}
],
"id": "{19529281-834e-4ef4-99cc-02b7e5fa34b9}",
"name": "product",
"type": "Product",
"artefactType": "MODINST",
"metaName": "C_PRODUCT",
"modelId": "{c7715a8e-6487-4a8b-8ab2-9d34b00c41c7}"
},
...
]
}
9.11 Object Relations
An API for retrieving a list of both incoming and outgoing relations for objects that are supported by a parent artefact.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/relations/{direction} Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {object-id} The ID of the object. The value must not contain brackets. {direction} The direction of the relation. Can be incoming or outgoing. Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document containing a list of available relations for given object. Each entry contain meta name, ui name and an amount of existing endpoints.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 84/181
9.11.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root relations/{direction}
2 Parent link parent root objects
3 Link to every endpoint of relation
self relation relations/{direction}/{meta_name}
9.11.2 Object Relations Result Example
Here is a GET request that returns an outgoing relations list in an XML reprentation:
REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing Accept: application/xml
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<locale>en</locale>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing" method="GET" rel="self" />
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5" method="GET" rel="parent" />
</rest_links>
<relations>
<relation metaName="RC_REFERENCED_IT_SYSTEM_MODEL">
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 85/181
926c4b5cdbe5/relations/outgoing/RC_REFERENCED_IT_SYSTEM_MODEL" method="GET" rel="self" />
</rest_links>
<name>
<![CDATA[Referenced IT system model]]>
</name>
<numberOfEndpoints>
<![CDATA[0]]>
</numberOfEndpoints>
</relation>
<relation metaName="RC_RESPONSIBLE_FOR_OQ">
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RESPONSIBLE_FOR_OQ" method="GET" rel="self" />
</rest_links>
<name>
<![CDATA[Responsible for open question]]>
</name>
<numberOfEndpoints>
<![CDATA[0]]>
</numberOfEndpoints>
</relation>
...
</relations>
</response>
Here is a GET request that returns an outgoing relations list in a JSON representation:
REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing
Accept: application/json
RESPONSE
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 86/181
{ "locale": "en",
"rest_links": [
{
"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing",
"method": "GET",
"rel": "self"
},
{
"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5",
"method": "GET",
"rel": "parent"
}
],
"relations": [
{
"rest_links": [
{
"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_REFERENCED_DOCUMENTS",
"method": "GET",
"rel": "self"
}
],
"relation": {
"metaName": "RC_REFERENCED_DOCUMENTS",
"name": "Referenced documents",
"numberOfEndpoints": 0
}
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 87/181
},
{
"rest_links": [
{
"href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_CONNECTOR",
"method": "GET",
"rel": "self"
}
],
"relation": {
"metaName": "RC_CONNECTOR",
"name": "Connector",
"numberOfEndpoints": 0
}
},
...
]
}
9.12 Object Relation Endpoints
An API for retrieving incoming or outgoing relation endpoints.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/relations/{direction}/{rel_name} Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {object-id} The ID of the object. The value must not contain brackets. {direction} The direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 88/181
Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document containing a list of endpoint relations of a specific type for the given object, basic information about "from" and "to" artefacts (id, metaName, ui name, type, and artefactType).
9.12.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root relations/{direction}/{rel_name}
2 Parent link parent root relations/{direction}
3 Link to relation details of every relation
self relation relations/{direction}/{rel_name}/{artefact_id}
4 Link to artefacts of every relation
self from or to objects/models/modelInstance
9.12.2 Object Relation Endpoint Result Example
Here is a GET request that returns an outgoing relation endpoints list in an XML representation:
REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R Accept: application/xml
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 89/181
<response>
<locale>en</locale>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R" method="GET" rel="self" />
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing" method="GET" rel="parent" />
</rest_links>
<relations>
<relation>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R/17d70f5d-684a-4c3d-bb02-095a309f089d" method="GET" rel="self" />
</rest_links>
<from>
<id>
<![CDATA[{0c301f28-6f53-4145-afe2-926c4b5cdbe5}]]>
</id>
<metaName>
<![CDATA[C_APPLICATION]]>
</metaName>
<name>
<![CDATA[Internet search engine]]>
</name>
<type>
<![CDATA[Application]]>
</type>
<artefactType>
<![CDATA[REPOSITORY_OBJECT]]>
</artefactType>
<rest_links>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 90/181
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5" method="GET" rel="self" />
</rest_links>
</from>
<to>
<id>
<![CDATA[{17d70f5d-684a-4c3d-bb02-095a309f089d}]]>
</id>
<metaName>
<![CDATA[C_RISK]]>
</metaName>
<name>
<![CDATA[Riskno2]]>
</name>
<type>
<![CDATA[Risk]]>
</type>
<artefactType>
<![CDATA[REPOSITORY_OBJECT]]>
</artefactType>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/17d70f5d-684a-4c3d-bb02-095a309f089d" method="GET" rel="self" />
</rest_links>
</to>
</relation>
...
</relations>
</response>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 91/181
Here is a GET request that returns an outgoing relation endpoints list in a JSON representation:
REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_
Accept: application/json
RESPONSE { "locale": "en", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R", "method": "GET", "rel": "self" }, { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing", "method": "GET", "rel": "parent" } ], "relations": [ { "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5/relations/outgoing/RC_RISK_R/17d70f5d-684a-4c3d-bb02-095a309f089d", "method": "GET", "rel": "self" } ], "from": { "id": "{0c301f28-6f53-4145-afe2-926c4b5cdbe5}", "metaName": "C_APPLICATION", "name": "Internet search engine", "type": "Application", "artefactType": "REPOSITORY_OBJECT",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 92/181
"rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/0c301f28-6f53-4145-afe2-926c4b5cdbe5", "method": "GET", "rel": "self" } ] }, "to": { "id": "{17d70f5d-684a-4c3d-bb02-095a309f089d}", "metaName": "C_RISK", "name": "Riskno2", "type": "Risk", "artefactType": "REPOSITORY_OBJECT", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/17d70f5d-684a-4c3d-bb02-095a309f089d", "method": "GET", "rel": "self" } ] } }, ... ] }
9.13 Object Relation Endpoint Details
An API for retrieving details of an incoming or outgoing relation endpoint.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/relations/{direction}/{rel_name}/{artefact_id} Identifiers
{repo-id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 93/181
{object-id} The ID of the object. The value must not contain brackets. {direction} The direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation. {artefact_id} The ID of the relation target artefact. The value must not contain brackets. Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document containing a "from" and "to" relations artefact, with metaName, ui name, type and artefact type, and a list of endpoint attributes containing ui name, metaName, attribute type and value.
9.13.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root relations/{direction}/{rel_name}/{artefact_id}
2 Relation endpoint patch link
patch root relations/{direction}/{rel_name}/{artefact_id}
3 Relation endpoint delete link
delete root relations/{direction}/{rel_name}/{artefact_id}
4 Parent link parent root relations/{direction}/{rel_name}
5 Link to each artefact
self "from" or "to" artefact
objects/models/modelInstance
9.13.2 Object Relation Endpoint Details Result Example
Here is a GET request that returns outgoing relation details (artefacts and attributes) in an XML representation:
REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577 Accept: application/xml
RESPONSE
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 94/181
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<locale>en</locale>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577" method="GET" rel="self" />
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577" method="PATCH" rel="patch" />
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577" method="DELETE" rel="delete" />
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R" method="GET" rel="parent" />
</rest_links>
<relation>
<from>
<id>
<![CDATA[{15d40171-08aa-4497-a090-86826eba1ed3}]]>
</id>
<metaName>
<![CDATA[C_PRODUCT]]>
</metaName>
<name>
<![CDATA[ProductTest]]>
</name>
<type>
<![CDATA[Product]]>
</type>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 95/181
<artefactType>
<![CDATA[REPOSITORY_OBJECT]]>
</artefactType>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3" method="GET" rel="self" />
</rest_links>
</from>
<to>
<id>
<![CDATA[{22e0edf2-952e-4e56-a229-961b8ddc0577}]]>
</id>
<metaName>
<![CDATA[C_RISK]]>
</metaName>
<name>
<![CDATA[Riskno1]]>
</name>
<type>
<![CDATA[Risk]]>
</type>
<artefactType>
<![CDATA[REPOSITORY_OBJECT]]>
</artefactType>
<rest_links>
<rest_link href="http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/22e0edf2-952e-4e56-a229-961b8ddc0577" method="GET" rel="self" />
</rest_links>
</to>
<attributes>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 96/181
<attribute metaName="NAME" attrType="ADOSTRING" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="string">
<name>
<![CDATA[Name]]>
</name>
<value></value>
</attribute>
</attributes>
</relation>
</response>
Here is a GET request that returns outgoing relation details (artefacts and attributes) in a JSON representation:
REQUEST GET rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577
Accept: application/json
RESPONSE { "locale": "en", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577", "method": "GET", "rel": "self" }, { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577", "method": "PATCH", "rel": "patch" }, "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 97/181
"method": "DELETE", "rel": "delete" }, { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3/relations/outgoing/RC_RISK_R", "method": "GET", "rel": "parent" } ], "from": { "id": "{15d40171-08aa-4497-a090-86826eba1ed3}", "metaName": "C_PRODUCT", "name": "ProductTest", "type": "Product", "artefactType": "REPOSITORY_OBJECT", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/15d40171-08aa-4497-a090-86826eba1ed3", "method": "GET", "rel": "self" } ] }, "to": { "id": "{22e0edf2-952e-4e56-a229-961b8ddc0577}", "metaName": "C_RISK", "name": "Riskno1", "type": "Risk", "artefactType": "REPOSITORY_OBJECT", "rest_links": [ { "href": "http://localhost:8000/ADOXXWEB/rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/22e0edf2-952e-4e56-a229-961b8ddc0577", "method": "GET", "rel": "self" } ] }, "attributes": [ {
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 98/181
"name": "Name", "metaName": "NAME", "attrType": "ADOSTRING", "value": "" } ] }
10 Repository Write APIs
This section lists the available repository write APIs.
10.1 Repository Objects
10.1.1 Create Object
An API for creating new repository objects. After execution, a new object resource with a unique ID will be created. If successful, a 201 status will be returned with the full resource body and a link to the new resource available in the "Location" header.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objects Identifiers {repo_id} ID of the repository Body Content-type:application/json
The following properties can be set at root level: name, metaName, groupId, attributes.
• The "name" and "metaName" properties are required for object creation, otherwise a bad request (400) status is returned.
• The property "groupId" is optional, when not passed, the object will be created in the “_Unassigned” group.
• The property "attributes" is optional. NAME as an attribute is forbidden on object creation. • The Property "attributes" is a list of JSON objects. • The property "metaName" is required, "value" is required only if the attribute does not support
no value.
To set no value for a specific object attribute, the JSON attribute definition should have null value, e.g.
{
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 99/181
"name":"New Risk", "metaName":"C_RISK", "groupId":"{227f1a76-dd6f-4c03-aed9-36e07e82a14c}", "attributes": [ { "metaName": "A_DESCRIPTION", "value": "Description value to be set" }, { "metaName": "A_SHOW_SYMBOL_IF_COTROLS_EXIST", "value": true } ] } Request headers
Content-type: application/json
Accept: application/json and application/xml
Content-Language: ISO 639-1 language code
Response A JSON or XML document with newly created object information (see Object result example). Response Headers
Location
A link to the newly created resource.
e.g. http:/ ... /rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/602021e6-8a47-4b10-a8b8-ed0c325f129c
10.1.2 Delete Object
An API for deleting object resources. If successful, a 204 status will be returned without any content. A 404 status will be returned in case when the resource does not exist. In case the resource is locked, the status 423 Locked will be returned.
In case there are no access rights to the object, a 403 Forbidden status will be returned. A 409 Conflict status will be returned in case the repository object is referenced in any model.
HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/objects/{object_id} Identifiers
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 100/181
{repo_id} ID of the repository {object_id} ID of the object Response: No content
10.1.3 Modify Object
An API for editing object attributes. If successful, a 200 status will be returned with the full resource body and a link to the resource available in the "Location" header. A 404 status will be returned in case the resource does not exist. In case the resource is locked, a status 423 Locked will be returned.
In case there are no access rights to the object, a 403 Forbidden status will be returned.
HTTP Method PATCH URL path /rest/2.0/repos/{repo_id}/objects/{object_id} Identifiers {repo_id} ID of the repository {object_id} ID of the object Body Content-type: application/json
A JSON object containing list of attributes that needs to be updated. Language dependent values will only be updated for the language which is passed in request header.
Note: To set no value of a specific object attribute, the JSON attribute value should be null, .e.g.
{ "attributes": [ { "metaName": "A_DESCRIPTION", "value": "New description value to be set" }, { "metaName": "A_SHOW_SYMBOL_IF_COTROLS_EXIST", "value": true } ] } Request headers
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 101/181
Content-type: application/json
Content-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the updated object (see Object result example). Response Headers
Location
Link to modified object
e.g. http:/ ... /rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/602021e6-8a47-4b10-a8b8-ed0c325f129c
10.1.4 Move Object
An API for changing the parent group of a repository object. If successful, a 200 status will be returned with the full resource body and a link to the resource available in the "Location" header. A 404 status will be returned in case the resource (object or target object group) does not exist. In case the resource is locked, a status 423 Locked will be returned.
In case there are no access rights to the object or target group, a 403 Forbidden status will be returned.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objects/{object_id}/actions?type=move Identifiers {repo_id} ID of the repository {object_id} ID of the object Body Content-type: application/json
A JSON object containing the id of the group to which the resource should be relocated, .e.g.
{"groupId":"{96ced025-fc85-46a7-be44-eb29e6d5b5ad}"} Request headers Content-type: application/json and application/xml
Acceot-Language: ISO 639-1 language code Response A JSON or XML document with the moved object (see Object result example). Response Headers
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 102/181
Location
Link to the modified object
e.g.http:/.../rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/602021e6-8a47-4b10-a8b8-ed0c325f129c
10.2 Object Group
10.2.1 Create Object Group
An API for creating new object groups. If parentGroupId is not passed, the group will be created in the root object group.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objectgroups Identifiers {repo_id} ID of the repository Body Content-type:application/json
JSON properties:
• Name • parentGroupId - (optional) ID of the parent group
Sample data:
{ "name": "groupName", "parentGroupId" : "{cb2fdc3c-0a36-40ea-9150-35c7f5662357}" } Request headers
Content-type: application/json
Content-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the created object group (see Object Group example). Response Headers
Location A link to the newly created resource.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 103/181
e.g. http:/ ... /rest/2.0/repos/adff255a-9806-4e0b-8069-caeb2e59092e/objectgroups/96ced025-fc85-46a7-be44-eb29e6d5b5ad
10.2.2 Delete Object Group
An API for deleting object groups and sub groups. If successful, a 204 status will be returned without any content. A 404 status will be returned in case when the resource does not exist. In case the resource is locked, the status 423 Locked will be returned.
In case there are no access rights to the object group, a 403 Forbidden status will be returned. A 409 Conflict status will be returned in case the repository object is referenced in any model.
HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/objectgroups/{group-id}
/rest/2.0/repos/{repo_id}/objectgroups/{group-id}?recursive=true Identifiers {repo_id} ID of the repository {object_id} ID of the object Parameters Parameters should be inserted after the question mark, after {group-id}. Parameters are optional.
recursive (boolean)
Default false, if set to true then the whole tree beginning from the object group which ID was specified as group-id will be deleted.
Response: No content
10.2.3 Modify Object Group
APIs for modifying object groups.
Change Attributes
An API for modifying the name attribute of a group.
HTTP Method PATCH URL path /rest/2.0/repos/{repo_id}/objectgroups/{group_id} Identifiers {repo_id} ID of the repository {object_id} ID of the object
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 104/181
Body Content-type: application/json
A JSON object containing the “name” attribute. The name will only be updated for the language which is passed in request header.
Sample data:
{ "name":"newDefaultName" } Request headers
Content-type: application/json
Content-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the updated object group (see Object Group example). Response Headers
Location
A link to the modified object group.
e.g. http:/ ... /rest/2.0/repos/adff255a-9806-4e0b-8069-caeb2e59092e/objectgroups/96ced025-fc85-46a7-be44-eb29e6d5b5ad
Relocate Group
An API for moving an object group to another parent group.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objectgroups/{group_id}/actions?type=move Identifiers {repo_id} ID of the repository {object_id} ID of the object Parameters To perform a group relocation, the mandatory parameter "type" with value "move" is required in the URL. The parameter should be inserted after the question mark, after ../actions. Body Content-type: application/json
A JSON object containing the "targetGroupId" property which is the ID of the new parent group.
Sample data:
{
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 105/181
"targetGroupId":"{96ced025-fc85-46a7-be44-eb29e6d5b5ad}" } Request headers
Content-type: application/json
Accept-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the moved object group (see Object Group example). Response Headers
Location
A link to the moved object group.
e.g. http:/ ... /rest/2.0/repos/adff255a-9806-4e0b-8069-caeb2e59092e/objectgroups/89ced025-fc85-46a7-bu44-eb29e6d5b5ad
Relocate Elements
An API for moving repository objects to another object group. In the event of an error, there is information about which element caused the error and which elements were successfully moved.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objectgroups/{group_id}/actions?type=moveContainedElements Identifiers {repo_id} ID of the repository {object_id} ID of the object Parameters To perform a group relocation, the mandatory parameter "type" with value " moveContainedElements" is required in the URL. The parameter should be inserted after the question mark, after ../actions. Body Content-type: application/json
A JSON object containing the "targetGroupId" property which is the ID of the target group for moved objects and the "elementId" property which is a list of repository object ID elements.
Sample data:
{ "elementId":["{6768bc93-1c34-4143-94ea-60b685bdba97}", "{1c5dde0e-ec8d-42c3-9736-2ef65000be75}", "{76ced025-fc85-46a7-be44-eb29e6d5b5es}"], "targetGroupId":"{96ced025-fc85-46a7-be44-eb29e6d5b5ad}" }
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 106/181
Request headers
Content-type: application/json
Accept-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the target object group (see Object Group example). Response Headers
Location
A link to the target object group to which objects were moved.
e.g. http:/ ... /rest/2.0/repos/adff255a-9806-4e0b-8069-caeb2e59092e/objectgroups/96ced025-fc85-46a7-be44-eb29e6d5b5ad
10.3 Object Relations
10.3.1 Create Endpoint
An API for creating a new incoming or outgoing endpoint.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/objects/{group_id}/relations/{direction}/{rel_name} Identifiers {repo_id} ID of the repository {group_id} ID of the object {direction} Direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation Body Content-type:application/json
A JSON object containing:
• toId (for outgoing direction) / fromId (for incoming direction) • attributes (optional)
o metaName o value
• modelId (if relation is between modelling instances)
The property "attributes" is a list of JSON objects. The property "metaName" is required, "value" is required only if the attribute does not support no value.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 107/181
Sample data for outgoing:
{ "toId" : "{22e0edf2-952e-4e56-a229-961b8ddc0577}", "attributes" : [ { "metaName": "A_DESCRIPTION_CS", "value": "Description value to be set" }, { "metaName": "DENOMINATION", "value": "Rel name" } ] }
Sample data for incoming:
{ "fromId" : "{22e0edf2-952e-4e56-a229-961b8ddc0577}", "attributes" : [ { "metaName": "A_DESCRIPTION_CS", "value": "Description value to be set" }, { "metaName": "DENOMINATION", "value": "Rel name" } ] } Request headers
Content-type: application/json
Content-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the created relation (see Object relation endpoint details example). Response Headers
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 108/181
Location
A link to the newly created relation.
e.g. http:/.../rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/44f8be9e-93e5-4a69-bd14-6c69db4ee5b4/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577
10.3.2 Update Endpoint
An API for modifying attributes of an incoming or outgoing relation endpoint.
HTTP Method PATCH URL path /rest/2.0/repos/{repo_id}/objects/{group_id}/relations/{direction}/{rel_name}/{artefact_id} Identifiers {repo_id} ID of the repository {group_id} ID of the object {direction} Direction of the relation. Can be incoming or outgoing. {rel_name} Meta name of the relation {artefact_id} ID of the target artefact in relation Body Content-type:application/json
A JSON object containing:
• attributes o metaName o value
The property "attributes" is a list of JSON objects. The property "metaName" is required, "value" is required only if the attribute does not support no value.
Language dependent values will only be updated for the language which is passed in request header.
Sample data:
{ "attributes" : [ { "metaName": "NAME", "value": "New Relation Name" } ]
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 109/181
} Request headers
Content-type: application/json
Content-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the updated relation (see Object relation endpoint details example). Response Headers
Location
A link to the updated relation.
e.g. http:/.../rest/2.0/repos/d1dfe6b6-6176-4881-88c3-8e8b775546de/objects/44f8be9e-93e5-4a69-bd14-6c69db4ee5b4/relations/outgoing/RC_RISK_R/22e0edf2-952e-4e56-a229-961b8ddc0577
10.3.3 Delete Endpoint
An API for deleting an incoming or outgoing relation endpoint.
HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/objects/{group_id}/relations/{direction}/{rel_name}/{artefact_id} Identifiers {repo_id} ID of the repository {group_id} ID of the object {direction} Direction of relation. Can be incoming or outgoing. {rel_name} Meta name of the relation {artefact_id} ID of the target artefact in relation Response: No content A JSON or XML document with the updated relation (see Object relation endpoint details example).
11 Repository Search APIs
This section lists the available repository search APIs.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 110/181
11.1 Search Queries
Search queries have to be treated differently than the previous types of resources, as search queries are no actual resources that can be queried or modified.
11.1.1 Performing a Generic Search Query
An API for performing the query.
Important note: If no range is set (identifier {range-end}), 1000 objects are returned (from 0 to 999).
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/search/?query={filters:[{filter_object},{}…]}&range-start={range-start}&range-end={range-end}&attribute={attribute} Identifiers
{repo_id}
The ID of the repository that is used to perform the search. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/...
min = 1
max = 1
{query}
The search term that is used to perform the search. This parameter is passed as a JSON object called “filters” which is of type array. Each object on the array is a separate filter in terms of ado.query API.
e.g. …?query={"filters":[{className: "C_ACTOR"},{attrName: "A_DESCRIPTION", value: "This is a description", op: "OP_EQ"}]
filters: Filter object as defined by ado.query API. See section 11.1.4 for a summary.
min = 1
max = 1
{attribute}
Optional, defines the attributes of the result objects (models, objects) that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined, all attributes from the query are returned.
e.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION
min = 0
max = many
{range-start}
Optional, defines the start of the range of results to be fetched from the total result. A default value is 0.
e.g. …range-start=0
min=0 max=1
{range-end}
Optional, defines the end of the range of results to be fetched from the total result. A default value is not configurable yet. -1 denotes all results. By default 1000 objects are returned (from 0 to 999).
e.g. …range-end=10
min=0 max=1
Request headers Accept: application/json or application/xml (dictates response format)
Accept-Language: ISO 639-1 language code
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 111/181
Response A JSON or XML object with properties representing metadata of the response (number of total hits, etc.) and a nonnull array with result items. Each result item should in turn contain its meta data and a nonnull array with its properties.
11.1.2 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root search
2 Link to previous bundle of results(if existing)
previous root search
3 Link to next bundle of results(if existing)
next root search
4 Link to each result self item models/objects/modelling objects
5 Link to each relation target
self target models/objects/modelling objects
11.1.3 Result Examples for a Simple Query
Here is a GET request to fetch an object, requesting details in an XML representation:
REQUEST GET rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query={"filters":[{className:"C_ROLE"},{attrName:"NAME", value: "Manager", op:"OP_LIKE"}]}&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99
Accept: application/xml
Accept-Language : en RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 112/181
<response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query=%7B%22filters%22%3A%5B%7BclassName%3A%22C_ROLE%22%7D%2C%7BattrName%3A%22NAME%22%2C+value%3A+%22Manager%22%2C+op%3A%22OP_LIKE%22%7D%5D%7D&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99" method="GET" rel="self"/> </rest_links> <hitsTotal>7</hitsTotal> <locale>en</locale> <rangeStart>0</rangeStart> <rangeEnd>7</rangeEnd> <items> <item id="{a6633d0b-d5cc-4b69-bbea-0873061212be}" artefactType="REPOSITORY_OBJECT" metaName="C_ROLE"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/a6633d0b-d5cc-4b69-bbea-0873061212be" method="GET" rel="self"/> </rest_links> <name><![CDATA[Audit Manager]]></name> <type><![CDATA[Role]]></type> <link href="http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=a6633d0b-d5cc-4b69-bbea-0873061212be&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=a6633d0b-d5cc-4b69-bbea-0873061212be"/> <icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png" rel="icon"/> <attributes> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="A_DESCRIPTION" attrType="STRING" xsi:type="string"> <name><![CDATA[Description]]></name> <value/> </attribute> </attributes>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 113/181
</item> <item id="{ad74e247-929b-4344-9380-7604dcee608a}" artefactType="REPOSITORY_OBJECT" metaName="C_ROLE"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/ad74e247-929b-4344-9380-7604dcee608a" method="GET" rel="self"/> </rest_links> <name><![CDATA[Private Customer Account Manager]]></name> <type><![CDATA[Role]]></type> <link href="http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=ad74e247-929b-4344-9380-7604dcee608a&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=ad74e247-929b-4344-9380-7604dcee608a"/> <icon href="http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png" rel="icon"/> <attributes> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="A_DESCRIPTION" attrType="STRING" xsi:type="string"> <name><![CDATA[Description]]></name> <value/> </attribute> </attributes> </item> ... </items> </response>
Here is a GET request to fetch an object, requesting details in a JSON representation:
REQUEST GET rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query={"filters":[{className:"C_ROLE"},{attrName:"NAME", value: "Manager", op:"OP_LIKE"}]}&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99
Accept: application/json
Accept-Language : en
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 114/181
RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/search?query=%7B%22filters%22%3A%5B%7BclassName%3A%22C_ROLE%22%7D%2C%7BattrName%3A%22NAME%22%2C+value%3A+%22Manager%22%2C+op%3A%22OP_LIKE%22%7D%5D%7D&attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99", "method": "GET", "rel": "self" } ], "hitsTotal": 7, "locale": "en", "rangeStart": 0, "rangeEnd": 7, "items": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/a6633d0b-d5cc-4b69-bbea-0873061212be", "method": "GET", "rel": "self" } ], "id": "{a6633d0b-d5cc-4b69-bbea-0873061212be}", "name": "Audit Manager", "type": "Role", "artefactType": "REPOSITORY_OBJECT", "metaName": "C_ROLE", "link": {
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 115/181
"href": "http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=a6633d0b-d5cc-4b69-bbea-0873061212be&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=a6633d0b-d5cc-4b69-bbea-0873061212be" }, "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png", "rel": "icon" }, "attributes": [ { "name": "Description", "metaName": "A_DESCRIPTION", "attrType": "STRING", "value": "" } ] }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/repos/e1138bdc-4063-490e-95f8-986d18c79ac3/objects/ad74e247-929b-4344-9380-7604dcee608a", "method": "GET", "rel": "self" } ], "id": "{ad74e247-929b-4344-9380-7604dcee608a}", "name": "Private Customer Account Manager", "type": "Role", "artefactType": "REPOSITORY_OBJECT", "metaName": "C_ROLE", "link": {
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 116/181
"href": "http://localhost:8080/ADOxxWeb/?t=nb&at=0&id=ad74e247-929b-4344-9380-7604dcee608a&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=e1138bdc-4063-490e-95f8-986d18c79ac3&rid=ad74e247-929b-4344-9380-7604dcee608a" }, "icon": { "href": "http://localhost:8080/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png", "rel": "icon" }, "attributes": [ { "name": "Description", "metaName": "A_DESCRIPTION", "attrType": "STRING", "value": "" } ] }, ... ] }
11.1.4 Filters Definition
Filter objects may contain different properties depending on the used operator:
Operator Filters object
Empty Operator (OP_EMPTY) {attrName: "A_DESCRIPTION ", op: “OP_EMPTY”}
NoEmpty Operator (OP_NEMPTY)
{attrName: "A_DESCRIPTION ", op: “OP_NEMPTY” }
Like Operator (OP_LIKE) {attrName: "A_DESCRIPTION ", value: "string", op: “OP_LIKE”}
{attrName: "A_DESCRIPTION ", values: ["string1", "string2"], op: “OP_LIKE”}
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 117/181
Not Like Operator (OP_NLIKE) {attrName: "A_DESCRIPTION ", value: "string", op: “OP_NLIKE”}
Equal (OP_EQ) {attrName: "A_NEED_FOR_ACTION ", value: true, op: “OP_EQ”}
{attrName: "A_VALUE_AT_RISK ", value: [1, 2], op: “OP_EQ”}
NoEqual (OP_NEQ) {attrName: "A_NEED_FOR_ACTION ", value: true, op: “OP_NEQ”}
Greater (OP_GR) {attrName: "A_VALUE_AT_RISK ", value: 2, op: “OP_GR”}
Greater or equal (OP_GR_EQ) {attrName: "A_DESCRIPTION", value: "description", op: “OP_GR_EQ”}
Less (OP_LE) {attrName: "A_VALUE_AT_RISK ", value: 2, op: “OP_LE”}
Less or equal (OP_LE_EQ) {attrName: "A_DESCRIPTION", value: "description", op: “OP_LE_EQ”}
Regex Operator (OP_REGEX) {attrName: "A_DESCRIPTION", value: "^this is .*e$", op: “OP_REGEX”}
Range Operator (OP_RANGE) {attrName: "A_VALUE_AT_RISK", values: [1,3], op: “OP_RANGE”}
Not Range Operator (OP_NRANGE)
{attrName: "A_VALUE_AT_RISK", values: [1,3], op: “OP_NRANGE”}
Contains Any Operator (OP_CONTAINS_ANY)
{attrName: "APP", values:["v0", "v1", "v2"] op: “OP_CONTAINS_ANY”}
11.2 Search Jobs
An API for executing search queries using a POST job pattern. The request consists of three parts:
1. Prepare the query 2. Fetch the query result 3. Delete the query result
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 118/181
When you prepare the query, the search result is created temporarily as a resource on the server.
11.2.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root search jobs
2 Link to delete the search job
delete root search jobs
3 Link to previous bundle of results(if existing)
previous root search jobs
4 Link to next bundle of results(if existing)
next root search jobs
5 Link to each result self item models/objects/modelling objects
6 Link to each relation target
self target models/objects/modelling objects
11.2.2 Prepare Query
First you have to prepare the query result on the server by executing a query. After execution, a new resource with a unique key will be created. If the preparation succeeds, a 201 status will be returned with a link to the new resource available in the "Location" header. The new resource is valid for one hour from the last access to it.
HTTP Method POST URL path /rest/2.0/repos/{repo_id}/search/jobs Identifiers
{repo_id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... Body Content-type:application/json
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 119/181
The search term that is used to perform the search. Passed as a JSON object called “filters” which is of type array. Each object on the array is a separate filter in terms of ado.query API. See chapter 11.1.4 for a summary.
E.g. {"filters":[{className: "C_ACTOR"},{attrName: "A_DESCRIPTION", value: "This is a description", op: "OP_EQ"}] Response headers
Location
The Link to the newly created resource
E.g. http:/ ... /rest/2.0/repos/{repo_id}/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276
11.2.3 Fetch Query Result
After you have successfully prepared the query result on the server, the result or parts of it can be fetched using the resource ID.
HTTP Method GET URL path /rest/2.0/repos/{repo_id}/search/jobs/{key}?range-start={range-start}&range-end={range-end}&attribute={attribute}&input-key={input-key}&combine-type={combine-type} Identifiers
{repo_id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
e.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {key} Key of the job query resource
{attribute}
Optional, defines the attributes of the result objects (models, objects) that may be returned in results set. There can be multiple attributes within a request URL. If no attribute parameter is defined, all attributes from the query are returned.
e.g. &attribute=CUSTOM_ATTRIBUTE&attribute=A_DESCRIPTION
{range-start}
Optional, defines the start of the range of results to be fetched from the total result. A default value is 0.
e.g. …range-start=0
{range-end}
Optional, defines the end of the range of results to be fetched from the total result. A default value is not configurable yet. -1 denotes all results. By default 1000 objects are returned (from 0 to 999).
e.g. …range-end=10
{input-key} Optional, key of the job query resource. If this parameter is set, filters of both queries are merged during execution - intersect combiner type used.
{combine-type}
Optional, defines type of multiple queries combiner. Available types:
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 120/181
diff,
union,
intersect (default combiner) Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code Response A JSON or XML object with properties representing metadata of the response (number of total hits, etc.) and nonnull array with result items. Each result item should in turn contain its meta data and a nonnull array with its properties.
11.2.4 Delete Query Result
After you have fetched the relevant data, you should use the following API to delete the query result on the server. After execution, a query saved under the passed key will not be available anymore If the query succeeds, a 204 status will be returned without any content. A 204 status will also be returned in case a query saved under the passed key does not exist.
HTTP Method DELETE URL path /rest/2.0/repos/{repo_id}/search/jobs/{key} Identifiers
{repo_id}
The ID of the repository that is used to perform the request. The value must not contain brackets.
E.g. .../repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/... {key} The key of the job query resource. Response: No content
11.2.5 Example
Here is an example request to fetch an object, requesting details in an XML representation:
REQUEST 1 POST rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs
Body:
{"filters":[{className: "C_ROLE"},{attrName: "NAME", value: "Expert", op: "OP_EQ"}]}
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 121/181
Response headers:
Location: rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276Accept: application/xml
REQUEST 2 GET rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276?attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99 Accept: application/xml Accept-Language : en
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <hitsTotal>1</hitsTotal> - total amount of hits (range is not considered) <locale>en</locale> - language specified for the query <rangeStart>0</rangeStart> - start index of the results that should be returned <rangeEnd>1</rangeEnd> - rangeStart value + amount of returned results <items> - list of response objects/models <item id="{3cb965c2-6d95-4694-8f21-16e6e6f2bbdf}" metaName="C_ROLE"> - object/model id and (language independent) type <name><![CDATA[Expert]]></name> - name of an object/model (language specific) <type><![CDATA[Role]]></type> - type of an object/model (language specific) <link href="http://localhost/ADOxxWeb/?t=nb&at=0&id=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf"/> - direct url to an object/model
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 122/181
<icon href="http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png" rel="icon"/> - direct link to an object/model type icon and relation type <attributes> - list of item attributes <attribute xsi:type="string" metaName="A_DESCRIPTION" attrType="STRING"> - name of an attribute (language independent) and its value type <name><![CDATA[Description]]></name> - name of an attribute (language specific) <value><![CDATA[This is a description]]</value> - attribute value (language specific) </attribute> <attributes> <attribute xsi:type="string" metaName="A_IDENTIFICATION_OF_CHANGES_NCS" attrType="ENUM"> <name><![CDATA[Identification of changes]]></name> <value><![CDATA[No change]]</value> </attribute> <attributes> <attribute xsi:type="date" metaName="A_VALID_FROM_UTC" attrType="UTC"> <name><![CDATA[Valid from]]></name> <value><![CDATA[1970-01-01T01:00:00]]</value> </attribute> <attribute xsi:type="reference" metaName="RC_OWNER" attrType="RELATION"> <name><![CDATA[Process owner]]></name> <targets> - list of target objects/models <target id="{8fe990f8-245c-4b5c-b497-38defaab0172}" metaName="MT_BUSINESS_PROCESS_DIAGRAM_BPMN_20" direction="INCOMING"> - target object/model id, direction type and type (language independent) <name><![CDATA[BP Address change 1.00]]></name> - target object/model name (language specific) <type><![CDATA[Business Process Diagram]]></type> - target object/model type (language specific) <link href="http://localhost/ADOxxWeb/?t=nb&at=1&id=8fe990f8-245c-4b5c-b497-
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 123/181
38defaab0172&classId=aee098ea-071d-4150-8ce9-011eaf93643f&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=8fe990f8-245c-4b5c-b497-38defaab0172"/> <icon href="http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Baee098ea-071d-4150-8ce9-011eaf93643f%7D.png" rel="icon"/> </target > </targets> </attribute> </attributes> </item> </items> </response>
Here is an example request to fetch an object, requesting details in a JSON representation:
REQUEST 1 POST rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs
Body:
{"filters":[{className: "C_ROLE"},{attrName: "NAME", value: "Expert", op: "OP_EQ"}]}
Response headers:
Location: rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276
REQUEST 2 GET rest/2.0/repos/5ec4e2dc-82c4-41d3-ad69-620cded63d0e/search/jobs/8f8e30d8-f79c-4c03-b27e-de2742d95276?attribute=A_DESCRIPTION&attribute=RC_OWNER&range-start=0&range-end=99 Accept: application/json Accept-Language : en
RESPONSE { "hitsTotal": 1, - total amount of hits (range is not considered) "locale": "en", - language specified for the query "rangeStart": 0, - start index of the results that should be returned "rangeEnd": 1, - rangeStart value + amount of returned results "items": [ - list of response objects/models { "id": "{3cb965c2-6d95-4694-8f21-16e6e6f2bbdf}", - object/model id "name": "Expert", - name of an object/model (language specific)
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 124/181
"type": "Role", - type of an object/model (language specific) "metaName": "C_ROLE", - type of an object/model (language independent) "link": { - direct url to an object/model "href": "http://localhost/ADOxxWeb/?t=nb&at=0&id=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf&classId=38c98349-4425-40f7-8712-2d90e014228c&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=3cb965c2-6d95-4694-8f21-16e6e6f2bbdf" }, "icon": { - direct link to an object/model type icon "href": "http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7B38c98349-4425-40f7-8712-2d90e014228c%7D.png", "rel": "icon" - type of link relation }, "attributes": [ - list of item attributes { "name": "Description", - attribute name (language specific) "metaName": "A_DESCRIPTION", - attribute name (language independent) "attrType": "STRING", - attribute value type "value": "This is a description" - attribute value (language specific) },{ "name": "Identification of changes", "metaName": "A_IDENTIFICATION_OF_CHANGES_NCS", "attrType": "ENUM", "value": "No change" },{ "name": "Valid from", "metaName": "A_VALID_FROM_UTC", "attrType": "UTC", "value": "1970-01-01T01:00:00" },{ "name": "Process owner", "metaName": "RC_OWNER", "attrType": "RELATION", "targets": [ - list of target objects/models { "id": "{8fe990f8-245c-4b5c-b497-38defaab0172}",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 125/181
"name": "BP Address change 1.00", - target object/model name (language specific) "type": "Business Process Diagram", - type of the object/model (language specific) "metaName": "MT_BUSINESS_PROCESS_DIAGRAM_BPMN_20", - type of the object/model (language independent) "direction": "INCOMING", - direction of a relation "link": { "href": "http://localhost/ADOxxWeb/?t=nb&at=1&id=8fe990f8-245c-4b5c-b497-38defaab0172&classId=aee098ea-071d-4150-8ce9-011eaf93643f&repoid=5ec4e2dc-82c4-41d3-ad69-620cded63d0e&rid=8fe990f8-245c-4b5c-b497-38defaab0172" }, "icon": { "href": "http://localhost/ADOxxWeb/images/icons/ADONIS_BPMS_APPLICATION_LIBRARY_40%248.1/%7Baee098ea-071d-4150-8ce9-011eaf93643f%7D.png", "rel": "icon" } } ] } ] } ] }
12 User Read APIs
This section lists the available user read APIs.
12.1 User group
An API for retrieving a user group.
HTTP Method GET URL path /rest/2.0/usergroups/{group-id}
/rest/2.0/usergroups/{group-id}?recursive=true Identifiers {group-id} The ID of the group to be retrieved, root for the root user group. Request headers
Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 126/181
Parameters
There is one optional Boolean flag. It should be inserted after the question mark, after {group-id}.
recursive If this flag is set to true, the whole tree is returned, beginning from the user group whose ID was specified as group ID.
Response A JSON or XML document consisting of ID, name, list of contained groups (ID and name), list of contained users (ID, type, name)
12.1.1 HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self group usergroups
2 Link to parent user group (if it exists) parent group usergroups
3 Link to every user that is included in the group
self user users
5 Link to every subgroup self subgroup usergroups
12.1.2 User Group Result Example
Here is a GET request that returns user group information in an XML representation:
REQUEST GET rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <locale>en</locale> <group id="{a18c6786-7f19-455e-b666-e51d9ade038e}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e" method="GET" rel="self"/> </rest_links> <name><![CDATA[ADO_ROOT_OBJECT_GROUP]]></name> <subgroups> <group id="{227f1a76-dd6f-4c03-aed9-36e07e82a14c}"> <rest_links>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 127/181
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c" method="GET" rel="self"/> </rest_links> <name><![CDATA[ADOmoney Designer]]></name> </group> ... </subgroups> <users> <user id="{6e1ffeab-b246-47d1-909f-6fadf55d33ac}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[Admin]]></loginName> <firstName/> <lastName/> </user> ... </users> </group> </response>
Here is a GET request that returns user group information in a JSON representation:
REQUEST GET rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e
Accept: application/json
Accept-Language : en
RESPONSE { "locale": "en", "group": { "id": "{a18c6786-7f19-455e-b666-e51d9ade038e}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e", "method": "GET", "rel": "self" } ], "name": "ADO_ROOT_OBJECT_GROUP", "subgroups": [ { "id": "{227f1a76-dd6f-4c03-aed9-36e07e82a14c}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c", "method": "GET", "rel": "self"
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 128/181
} ], "name": "ADOmoney Designer" }, ... ], "users": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac", "method": "GET", "rel": "self" } ], "id": "{6e1ffeab-b246-47d1-909f-6fadf55d33ac}", "loginName": "Admin", "firstName": "", "lastName": "" }, ... ] } }
An XML representation with an additional parameter:
REQUEST GET rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e?recursive=true
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response>
<locale>en</locale>
<group id="{a18c6786-7f19-455e-b666-e51d9ade038e}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e?recursive=true" method="GET" rel="self"/>
</rest_links>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 129/181
<name><![CDATA[ADO_ROOT_OBJECT_GROUP]]></name>
<subgroups>
<group id="{227f1a76-dd6f-4c03-aed9-36e07e82a14c}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c" method="GET" rel="self"/>
</rest_links>
<name><![CDATA[ADOmoney Designer]]></name>
<subgroups>
<group id="{8dfc7c8d-1272-44bb-8213-e913833fdee1}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/8dfc7c8d-1272-44bb-8213-e913833fdee1" method="GET" rel="self"/>
</rest_links>
<name><![CDATA[ADOmoney Designer Inner]]></name>
<subgroups>
...
</subgroups>
<users>
<user id="{c379b6df-b962-466a-bce3-63c4ec7cf9e3}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/c379b6df-b962-466a-bce3-63c4ec7cf9e3" method="GET" rel="self"/>
</rest_links>
<loginName><![CDATA[User]]></loginName>
<firstName/>
<lastName/>
</user>
...
</users>
</group>
</subgroups>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 130/181
<users>
<user id="{45209445-7dca-44b6-9ca4-c55f5efdda12}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12" method="GET" rel="self"/>
</rest_links>
<loginName><![CDATA[andrew]]></loginName>
<firstName><![CDATA[Andrew]]></firstName>
<lastName><![CDATA[Initiative]]></lastName>
</user>
...
</users>
</group>
...
</subgroups>
<users>
<user id="{6e1ffeab-b246-47d1-909f-6fadf55d33ac}">
<rest_links>
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac" method="GET" rel="self"/>
</rest_links>
<loginName><![CDATA[Admin]]></loginName>
<firstName/>
<lastName/>
</user>
</users>
</group>
</response>
A JSON representation with additional parameters:
REQUEST
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 131/181
GET rest/2.0/repos/6f68b2e6-c48e-4bc5-a803-90cda4d17cf5/objectgroups/7e749f24-7a20-41e2-b3b2-132fd0d98392?icon=true&recursive=true
Accept: application/json
Accept-Language : en
RESPONSE {
"locale": "en",
"group": {
"id": "{a18c6786-7f19-455e-b666-e51d9ade038e}",
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/a18c6786-7f19-455e-b666-e51d9ade038e?recursive=true",
"method": "GET",
"rel": "self"
}
],
"name": "ADO_ROOT_OBJECT_GROUP",
"subgroups": [
{
"id": "{227f1a76-dd6f-4c03-aed9-36e07e82a14c}",
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/227f1a76-dd6f-4c03-aed9-36e07e82a14c",
"method": "GET",
"rel": "self"
}
],
"name": "ADOmoney Designer",
"subgroups": [
{
"id": "{8dfc7c8d-1272-44bb-8213-e913833fdee1}",
"rest_links": [
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 132/181
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/8dfc7c8d-1272-44bb-8213-e913833fdee1",
"method": "GET",
"rel": "self"
}
...
],
"name": "ADOMoney Designer Inner",
"subgroups": [
...
],
"users": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/c379b6df-b962-466a-bce3-63c4ec7cf9e3",
"method": "GET",
"rel": "self"
}
],
"id": "{c379b6df-b962-466a-bce3-63c4ec7cf9e3}",
"loginName": "User",
"firstName": "",
"lastName": ""
},
...
]
},
...
],
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 133/181
"users": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12",
"method": "GET",
"rel": "self"
}
],
"id": "{45209445-7dca-44b6-9ca4-c55f5efdda12}",
"loginName": "andrew",
"firstName": "Andrew",
"lastName": "Initiative"
},
...
]
},
...
],
"users": [
{
"rest_links": [
{
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/6e1ffeab-b246-47d1-909f-6fadf55d33ac",
"method": "GET",
"rel": "self"
}
],
"id": "{6e1ffeab-b246-47d1-909f-6fadf55d33ac}",
"loginName": "Admin",
"firstName": "",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 134/181
"lastName": ""
},
...
]
}
}
12.2 Roles
APIs for retrieving information about roles.
12.2.1 List of Role Grouping Items
Here is an API for retrieving a list of grouping items containing roles.
Note: An example for a grouping item is the ADONIS NP-specific group “Model Release Workflow” which contains the roles “Administrator”, “Modeller” etc.
HTTP Method GET URL path /rest/2.0/roles Request headers Accept: application/json and application/xml
Response A JSON or XML document consisting of IDs of role grouping items. For roles which are not attached to any grouping item technical group with ID none is returned.
HATEOAS Links
# Description rel Position in response Endpoint
1 Self link self root roles
2 Link to grouping item self item roles/id
Example Responses
Here is a GET request to get role grouping items information in an XML representation:
REQUEST
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 135/181
GET rest/2.0/roles
Accept: application/xml
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles" method="GET" rel="self"/> </rest_links> <items> <item id="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9" method="GET" rel="self"/> </rest_links> </item> <item id="none"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none" method="GET" rel="self"/> </rest_links> </item> </items> </response>
Here is a GET request to get role grouping items in a JSON representation:
REQUEST GET rest/2.0/repos
Accept: application/json
RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles", "method": "GET", "rel": "self" } ], "items": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9", "method": "GET", "rel": "self" }
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 136/181
], "id": "{3ad30848-5a75-484c-b27c-5ab621932dc9}" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none", "method": "GET", "rel": "self" } ], "id": "none" } ] }
12.2.2 List of Roles inside Grouping Item
Here is an API for retrieving a list of roles contained in a specified grouping item.
HTTP Method GET URL path /rest/2.0/roles/{id} Identifiers
{id} The ID of the role grouping item to be retrieved, none for a technical grouping item containing roles which are not attached to any grouping item.
Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document consisting of the ID of a grouping item and a list of roles assigned to this grouping item. Roles only contain information about grouping ID, meta name and name.
HATEOAS Links
# Description rel Position in response Endpoint
1 Self link self root roles/id
2 Link to list of grouping items parent root roles
3 Link to role self role roles/id/name
Example Responses
Here is a GET request to get roles inside a grouping item in an XML representation:
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 137/181
REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response id="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <locale>en</locale> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles" method="GET" rel="parent"/> </rest_links> <roles> <role metaName="REVIEWER (B)" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29" method="GET" rel="self"/> </rest_links> <name><![CDATA[Reviewer (business)]]></name> </role> <role metaName="ADMIN" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/ADMIN" method="GET" rel="self"/> </rest_links> <name><![CDATA[Administrator]]></name> </role> </roles> </response>
Here is a GET request to get roles inside a grouping item in a JSON representation:
REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9
Accept: application/json
Accept-Language : en
RESPONSE { "locale": "en", "response": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "rest_links": [ {
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 138/181
"href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles", "method": "GET", "rel": "parent" } ], "roles": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29", "method": "GET", "rel": "self" } ], "metaName": "REVIEWER (B)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Reviewer (business)" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/ADMIN", "method": "GET", "rel": "self" } ], "metaName": "ADMIN", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Administrator" } ] }
12.2.3 Detailed Role Information
Here is an API for retrieving detailed information about a specified role.
HTTP Method GET URL path /rest/2.0/roles/{id}/{name} Identifiers
{id} The ID of the role grouping item to be retrieved, none for a technical grouping item containing roles which are not attached to any grouping item.
{name} Meta name of the role. The name must be in encoded form and spaces must be represented as %20.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 139/181
Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document consisting of the ID of the meta name, ID of the grouping element, is role enabled, is system role, is role registered, is role relevant for metamodel rights and a list of users which are assigned to this role. Only basic user data are returned like ID, login name, first name and last name.
HATEOAS Links
# Description rel Position in response Endpoint
1 Self link self role roles/id/name
2 Link to parent grouping item parent role roles/id
3 Link to user self user users
Example Responses
Here is a GET request to get detailed role information in a XML representation:
REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29
Accept: application/xml
Accept-Language : en
RESPONSE HTTP/1.1 200 OK Content-Type: application/xml Content-Length: ... <response> <locale>en</locale> <role metaName="REVIEWER (B)" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}" enabled="true" system="false" registered="false" mmRights="false"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9" method="GET" rel="parent"/> </rest_links> <name><![CDATA[Reviewer (business)]]></name> <users> <user id="{45209445-7dca-44b6-9ca4-c55f5efdda12}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12" method="GET" rel="self"/>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 140/181
</rest_links> <loginName><![CDATA[andrew]]></loginName> <firstName><![CDATA[Andrew]]></firstName> <lastName><![CDATA[Initiative]]></lastName> </user> <user id="{4e27ebd4-796a-4614-abd6-0af61a48a94a}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[susan]]></loginName> <firstName><![CDATA[Susan]]></firstName> <lastName><![CDATA[Compliance]]></lastName> </user> </users> </role> </response>
Here is a GET request to get detailed role information in a JSON representation:
REQUEST GET rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29
Accept: application/json
Accept-Language : en
RESPONSE { "locale": "en", "item": { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28B%29", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9", "method": "GET", "rel": "parent" } ], "metaName": "REVIEWER (B)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Reviewer (business)", "enabled": true, "system": false, "registered": false, "mmRights": false, "users": [ { "rest_links": [
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 141/181
{ "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/45209445-7dca-44b6-9ca4-c55f5efdda12", "method": "GET", "rel": "self" } ], "id": "{45209445-7dca-44b6-9ca4-c55f5efdda12}", "loginName": "andrew", "firstName": "Andrew", "lastName": "Initiative" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a", "method": "GET", "rel": "self" } ], "id": "{4e27ebd4-796a-4614-abd6-0af61a48a94a}", "loginName": "susan", "firstName": "Susan", "lastName": "Compliance" } ] } }
12.3 Users
APIs for retrieving information about users.
12.3.1 Get the Specified User
Here is an API for retrieving users by login name or ID.
HTTP Method GET URL path /rest/2.0/users/login/{login_name}?attribute={attribute}
/rest/2.0/users/id/{id_of_user}?attribute={attribute} Identifiers {user-id} or {login-name} The ID or login name of the user to be retrieved
{attribute}
Optional, defines the attributes of the user that may be returned in the results set. There can be multiple attributes within a request URL. If no attribute parameter is defined all attributes of the user are returned.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 142/181
E.g. &attribute=FORENAME&attribute=EMAIL Request headers Accept: application/json and application/xml
Accept-Language: ISO 639-1 language code
Response A JSON or XML document consisting of all the basic information about the specified user: login name, ID, list of roles (ui name, meta name , mfbID and HATEOAS link to each), list of repositories (ID,name) to which user has access, does user have admin rights, is user a system user and user attributes.
HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root users
2 Link to each user group in which user is registered
parent root usergroups
3 Link to each role of the user self user roles
Example Responses
Here is a GET request to get user information in an XML representation:
REQUEST GET rest/2.0/users/login/peter or rest/2.0/users/id/8a080580-fa71-4868-81b4-3bb03b972704
Accept: application/xml
Accept-Language : en
RESPONSE <response> <locale>en</locale> <user id="{8a080580-fa71-4868-81b4-3bb03b972704}" admin="false" system="false"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter" method="GET" rel="self"/> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter" method="DELETE" rel="delete"/> </rest_links> <loginName><![CDATA[peter]]></loginName> <roles> <role metaName="Common"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Common" method="GET" rel="self"/>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 143/181
</rest_links> <name><![CDATA[Design & Document]]></name> </role> <role metaName="MODELLER" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/MODELLER" method="GET" rel="self"/> </rest_links> <name><![CDATA[Modeller]]></name> </role> <role metaName="REVIEWER (M)" parentId="{3ad30848-5a75-484c-b27c-5ab621932dc9}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28M%29" method="GET" rel="self"/> </rest_links> <name><![CDATA[Reviewer (methodical)]]></name> </role> <role metaName="Reader"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reader" method="GET" rel="self"/> </rest_links> <name><![CDATA[Read & Explore]]></name> </role> <role metaName="Reviewer"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reviewer" method="GET" rel="self"/> </rest_links> <name><![CDATA[Control & Release]]></name> </role> </roles> <repos> <repo id="{02388b8c-c8f3-4bd4-b9bb-a109bb4326b8}"> <name><![CDATA[Standard-Repository]]></name> </repo> </repos> <usergroups> <group id="{db977b96-c704-4926-9305-7e86043f885a}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/db977b96-c704-4926-9305-7e86043f885a" method="GET" rel="self"/> </rest_links> <name><![CDATA[Default group]]></name> </group> </usergroups> <attributes> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="FORENAME" attrType="STRING" xsi:type="string"> <name><![CDATA[First name]]></name> <value><![CDATA[Peter]]></value>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 144/181
</attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="SURNAME" attrType="STRING" xsi:type="string"> <name><![CDATA[Last name]]></name> <value><![CDATA[Risk]]></value> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="MUST_CHANGE_PASSWORD" attrType="INTEGER" xsi:type="number"> <name><![CDATA[User must change the password]]></name> <value><![CDATA[1.0]]></value> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="ACCOUNT_DISABLED" attrType="INTEGER" xsi:type="number"> <name><![CDATA[Account disabled]]></name> <value><![CDATA[0.0]]></value> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="TELEPHONE_NUMBER" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Telephone number]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="DESCRIPTION" attrType="LONGSTRING" xsi:type="string"> <name><![CDATA[User-specific Information]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="EMAIL" attrType="STRING" xsi:type="string"> <name><![CDATA[Email]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="ROOM" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Room]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="TYPE_OF_OCCUPATION" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Type of occupation]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="FORM_OF_ADDRESS" attrType="SHORTSTRING" xsi:type="string"> <name><![CDATA[Form of address]]></name> <value/> </attribute> <attribute xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" metaName="INACTIVE_SINCE" attrType="UTC" xsi:type="date"> <name><![CDATA[Inactive since]]></name> <value><![CDATA[1970-01-01T00:00:00]]></value> </attribute> </attributes> </user> </response>
Here is a GET request to get user information in a JSON representation:
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 145/181
REQUEST GET rest/2.0/users/login/peter or rest/2.0/users/id/8a080580-fa71-4868-81b4-3bb03b972704
Accept: application/json
Accept-Language : en
RESPONSE { "locale": "en", "user": { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter", "method": "GET", "rel": "self" }, { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/login/peter", "method": "DELETE", "rel": "delete" } ], "id": "{8a080580-fa71-4868-81b4-3bb03b972704}", "loginName": "peter", "roles": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Common", "method": "GET", "rel": "self" } ], "metaName": "Common", "name": "Design & Document" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/MODELLER", "method": "GET", "rel": "self" } ], "metaName": "MODELLER", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Modeller" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/3ad30848-5a75-484c-b27c-5ab621932dc9/REVIEWER%20%28M%29", "method": "GET", "rel": "self"
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 146/181
} ], "metaName": "REVIEWER (M)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}", "name": "Reviewer (methodical)" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reader", "method": "GET", "rel": "self" } ], "metaName": "Reader", "name": "Read & Explore" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/roles/none/Reviewer", "method": "GET", "rel": "self" } ], "metaName": "Reviewer", "name": "Control & Release" } ], "repos": [ { "id": "{02388b8c-c8f3-4bd4-b9bb-a109bb4326b8}", "name": "Standard-Repository" } ], "usergroups": [ { "id": "{db977b96-c704-4926-9305-7e86043f885a}", "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/usergroups/db977b96-c704-4926-9305-7e86043f885a", "method": "GET", "rel": "self" } ], "name": "Default group" } ], "admin": false, "system": false, "attributes": [ { "name": "First name", "metaName": "FORENAME", "attrType": "STRING", "value": "Peter"
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 147/181
}, { "name": "Last name", "metaName": "SURNAME", "attrType": "STRING", "value": "Risk" }, { "name": "User must change the password", "metaName": "MUST_CHANGE_PASSWORD", "attrType": "INTEGER", "value": 1 }, { "name": "Account disabled", "metaName": "ACCOUNT_DISABLED", "attrType": "INTEGER", "value": 0 }, { "name": "Telephone number", "metaName": "TELEPHONE_NUMBER", "attrType": "SHORTSTRING", "value": "" }, { "name": "User-specific Information", "metaName": "DESCRIPTION", "attrType": "LONGSTRING", "value": "" }, { "name": "Email", "metaName": "EMAIL", "attrType": "STRING", "value": "" }, { "name": "Room", "metaName": "ROOM", "attrType": "SHORTSTRING", "value": "" }, { "name": "Type of occupation", "metaName": "TYPE_OF_OCCUPATION", "attrType": "SHORTSTRING", "value": "" }, { "name": "Form of address", "metaName": "FORM_OF_ADDRESS", "attrType": "SHORTSTRING", "value": "" }, { "name": "Inactive since", "metaName": "INACTIVE_SINCE",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 148/181
"attrType": "UTC", "value": "1970-01-01T00:00:00" } ] } }
12.3.2 Users List
Here is an API for retrieving a flat users list.
HTTP Method GET URL path /rest/2.0/users Request headers Accept: application/json and application/xml
Response A JSON or XML document consisting of a flat list of users with basic info (ID and loginName).
HATEOAS Links
# Description rel Position in response
Endpoint
1 Self link self root users
2 Link to every user that is included in the list
self users users
Example Responses
Here is a GET request to get a users list in an XML representation:
REQUEST GET rest/2.0/users
Accept: application/xml
RESPONSE <response> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users" method="GET" rel="self"/> </rest_links> <users> <user id="{4e27ebd4-796a-4614-abd6-0af61a48a94a}"> <rest_links>
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 149/181
<rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[susan]]></loginName> </user> <user id="{a0f33384-3ac6-44ae-a898-8f855633bbbd}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/a0f33384-3ac6-44ae-a898-8f855633bbbd" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[rich]]></loginName> </user> <user id="{d329114f-2ad3-415f-9bfe-8b8b4b182aba}"> <rest_links> <rest_link href="http://localhost:8080/ADOxxWeb/rest/2.0/users/id/d329114f-2ad3-415f-9bfe-8b8b4b182aba" method="GET" rel="self"/> </rest_links> <loginName><![CDATA[reader]]></loginName> </user> ... </users> </response>
Here is a GET request to get a users list in a JSON representation:
REQUEST GET rest/2.0/users
Accept: application/json
RESPONSE { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users", "method": "GET", "rel": "self" } ], "users": [ { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/4e27ebd4-796a-4614-abd6-0af61a48a94a", "method": "GET", "rel": "self" } ], "id": "{4e27ebd4-796a-4614-abd6-0af61a48a94a}", "loginName": "susan" },
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 150/181
{ "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/a0f33384-3ac6-44ae-a898-8f855633bbbd", "method": "GET", "rel": "self" } ], "id": "{a0f33384-3ac6-44ae-a898-8f855633bbbd}", "loginName": "rich" }, { "rest_links": [ { "href": "http://localhost:8080/ADOxxWeb/rest/2.0/users/id/d329114f-2ad3-415f-9bfe-8b8b4b182aba", "method": "GET", "rel": "self" } ], "id": "{d329114f-2ad3-415f-9bfe-8b8b4b182aba}", "loginName": "reader" }, ... ] }
13 User Write APIs
This section lists the available user write APIs.
13.1 Users
13.1.1 Create Users
An API for creating new users. After execution, a new user resource with a unique ID will be created. If successful, a 201 status will be returned with a link to the new resource available in the "Location" header.
HTTP Method POST URL path /rest/2.0/users Body Content-type:application/json
The structure of the passed JSON object must be consistent with the "user" object property of the User response (see here). In addition, the "password" string property is required at the root level.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 151/181
The following properties can be set at root level: loginName, password, attributes, usergroups, repos, roles. The "loginName" and "password" properties are required for user creation, otherwise a bad request (400) status is returned. Other properties are optional.
The properties "repos", "usergroups", "roles" and "attributes" are lists of JSON objects. The property "id" is required for repos and usergroups the same as "metaName" for "attributes" and "roles".
A newly created user will be assigned to the default user group if no valid user group is passed within the body.
List of attributes available to set:
FORENAME, SURNAME, MUST_CHANGE_PASSWORD, ACCOUNT_DISABLED, TELEPHONE_NUMBER, DESCRIPTION, EMAIL, ROOM, TYPE_OF_OCCUPATION, FORM_OF_ADDRESS, INACTIVE_SINCE, LOGIN_MECHANISM, LDAP_GUID
To set no value for a specific user attribute the JSON attribute definition should have null value. Response Headers
Location A link to the newly created resource.
E.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Example: User Creation Body
"loginName":"NewUser",
"password":"Password123++",
"repos":[
{
"id":"{02388b8c-c8f3-4bd4-b9bb-a109bb4326b8}"
}
],
"usergroups":[
{
"id":"{227f1a76-dd6f-4c03-aed9-36e07e82a14c}"
},
{
"id":"{8bac4bcd-dfbb-4f1f-bcbb-e3b546d95c91}"
}
],
"attributes": [
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 152/181
{
"metaName": "FORENAME",
"value": "FirstName"
},
{
"metaName": "SURNAME",
"value": "LastName"
},
{
"metaName": "MUST_CHANGE_PASSWORD",
"value": 1
},
{
"metaName": "ACCOUNT_DISABLED",
"value": 0
},
{
"metaName":"TELEPHONE_NUMBER",
"value":"123 456 789"
},
{
"metaName":"DESCRIPTION",
"value":"User description"
},
{
"metaName":"EMAIL",
"value":"mail@mail"
},
{
"metaName":"ROOM",
"value":"Room"
},
{
"metaName":"TYPE_OF_OCCUPATION",
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 153/181
"value":"Type of occupation"
},
{
"metaName":"FORM_OF_ADDRESS",
"value":"Form of address"
}
],
"roles":[
{
"metaName": "REVIEWER (M)",
"parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}"
},
{
"metaName": "Reader"
}
]
}
13.1.2 Delete Users
An API for deleting user resources. If successful, a 204 status will be returned without any content.
HTTP Method DELETE URL path /rest/2.0/users/login/{login}
/rest/2.0/users/id/{user_id} Identifiers {login} Login of the user {user_id} ID of the user Response: No content Note: The users Admin and System cannot be deleted.
13.1.3 Modify Users
APIs for modifying user resources.
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 154/181
Update User Attributes
An API for editing user attributes. If successful, a 200 status will be returned with a full resource body.
HTTP Method PATCH URL path /rest/2.0/users/login/{login}
/rest/2.0/users/id/{user_id} Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json
A JSON object containing a list of attributes that need to be updated.
Note: To set no value of a specific user attribute, the JSON attribute value should be null .e.g.
PATCH /rest/2.0/users/login/{login}
Body of the PATCH request:
{ "attributes": [ { "metaName": "FORENAME", "value": "John" }, { "metaName": "SURNAME", "value": "Doe" } ] }
Request headers
Content-type: application/json
Content-Language: ISO 639-1 language code
Accept: application/json and application/xml
Response A JSON or XML document with the updated object (see User result example).
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 155/181
Response Headers
Location A link to the modified user.
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Assign User to User Group
An API for assigning users to user groups. If successful, a 201 status will be returned without any content.
HTTP Method POST URL path /rest/2.0/users/login/{login}/usergroups
/rest/2.0/users/id/{user_id}/usergroups Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json
JSON object containing usergroup id, e.g.
{ "groupId":"{6c81c50d-540f-4ed2-a453-372b1bec82d3}" } Response headers
Location Link to modified user
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Remove User from User Group
An API for removing users from user groups. If successful, a 204 status will be returned without any content.
HTTP Method DELETE URL path /rest/2.0/users/login/{login}/usergroups/{group_id}
/rest/2.0/users/id/{user_id}/usergroups/{group_id} Identifiers {login} Login of the user {user_id} ID of the user
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 156/181
{group_id} ID of the user group Response: No content Response headers
Location Link to modified user
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Assign User to Repository
An API for assigning users to repositories. If successful, a 204 status will be returned without any content.
HTTP Method POST URL path /rest/2.0/users/login/{login}/repos
/rest/2.0/users/id/{user_id}/repos} Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json
A JSON object containing the ID of the repository, e.g.
{ "repoId":"{6c81c50d-540f-4ed2-a453-372b1bec82d3}" } Response headers
Location Link to modified user
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Remove User from Repository
An API for removing users from repositories. If successful, a 204 status will be returned without any content.
HTTP Method DELETE URL path /rest/2.0/users/login/{login}/repos/{repo_id}
/rest/2.0/users/id/{user_id}/repos/{repo_id} Identifiers {login} Login of the user {user_id} ID of the user
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 157/181
{repo_id} ID of the repository Response: No content Response headers
Location Link to modified user
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Assign User to User Role
An API for assigning users to user roles. If successful, a 204 status will be returned without any content.
HTTP Method POST URL path /rest/2.0/users/login/{login}/roles
/rest/2.0/users/id/{user_id}/roles Identifiers {login} Login of the user {user_id} ID of the user Body Content-type: application/json
A JSON object containing the role name and ID of the role grouping item (if it exists), e.g.
{"metaName": "REVIEWER(M)", "parentId": "{3ad30848-5a75-484c-b27c-5ab621932dc9}"} Response: No content Response headers
Location Link to modified user
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
Remove User from User Role
An API for removing users from user roles. If successful, a 204 status will be returned without any content.
HTTP Method DELETE URL path /rest/2.0/users/login/{login}/roles/{id}/{name}
/rest/2.0/users/id/{user_id}/roles/{id}/{name} Identifiers {login} Login of the user {user_id} ID of the user
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 158/181
{id} ID of the role grouping item to be retrieved, none for technical grouping items containing roles which are not attached to any grouping item.
{name} Meta name of the role. The name must be in encoded form and spaces must be represented as %20.
Response: No content Response headers
Location Link to modified user
e.g. http:/ ... /rest/2.0/users/id/5945b96f-b2e8-4890-808c-14f383a66156
14 Error Handling All REST APIs have to support these HTTP status codes:
15 Appendix
15.1 Sample Implementation (Java): Programmatic Access
Programmatic access to an available RESTful service can be established using any programming language providing the required API to access an HTTP or HTTPS URL.
The simplest way of consuming a RESTful service is by using an HTTP GET request (provided that the service is implemented to respond to HTTP GET requests). When using HTTP GET, parameters will simply be added to the URL.
The following is a basic example of accessing the public (no authentication required) connection test service with a small Java program. In this example, the service does not require any parameters.
import java.io.IOException; import org.apache.http.client.ClientProtocolException;
HTTP status codes 200 OK requested object representation returned in response body 201 Created resource was successfully created and link to it is returned in Location header 204 No Content request was successfully executed and there is no content in response 400 Bad request the request could not be understood by the server 401 Unauthorized authentication information does not map to an authorized client 403 Forbidden resource cannot be accessed 404 Not Found resource does not exist 409 Conflict Resource is referenced by another resource 423 Locked Resource is locked 500 Internal Server Error processing of the request failed
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 159/181
import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; public class RESTClient {
private static final String CONNECTION_PATH = "http://localhost:8080/ADOxxWeb/rest/connection";
public static void main (final String [] args) throws ClientProtocolException, IOException
{ final CloseableHttpClient aClient = HttpClients.createDefault (); final HttpGet aMethod = new HttpGet (CONNECTION_PATH); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try {
System.out.println ("Response From RESTful service: \n" + EntityUtils.toString (aResponse.getEntity (), “UTF-8”)); } finally {
aResponse.close (); }
} }
Running this example should provide a response similar to the following: Response From RESTful service: REST Connection Service Evaluation invoked @ Mon Feb 10 16:10:33 CET 2014
15.2 Sample Implementation (Java): Authenticated REST call
The following code shows how to perform authorized access using HTTP GET to the test service which is available at ../rest/connection/auth (e.g. http://localhost:8080/ ADOxxWeb /rest/connection/auth): import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map;
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 160/181
import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class AuthRESTClient {
private static final String CONNECTION_PATH = "http://localhost:8080/ADOxxWeb/rest/connection/auth";
public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException
{ final CloseableHttpClient aClient = HttpClients.createDefault (); final HttpGet aMethod = new HttpGet (CONNECTION_PATH); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); final String sIdentifier = "boc.rest.key.mfb.StandardRESTfulServices"; final String sSecret = "2edb376a-88d7-4564-a4cb-9fcdd005c8179427ccbd-89eb-45ea-a3ed-69f0d7c38e94f723beea-f2bc-4007-a238-8d9a0c88f8ed22365ab7-ff76-440b-99f8-1dc862e1607d3b2c7138-cba5-4a1e-9a66-00595b2524206ffa0893-4d41-4ba5-a43a-e15b5c9292713b3f066f-2875-4bd0-a49b-a093085c15db1224fc34-6d4d-4c62-a0b1-4aae1dffff6ddb1255c1-ca9a-4d58-9bfd-235c9c9f879869ed9de3-d641-4425-85d2-6f0c7a5d162407be6866-cd04-4fb9-b132-116321cec844ac27c950-ba19-4018-bd93- 38ce70f3ea1c60aae62c-e620-4762-a7a0-39d7f0b6c677176cc895-04c6-4d44-8767-4277ee315cfcbed1341f"; aMethod.addHeader ("x-axw-rest-identifier", sIdentifier); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); final Map <String, String []> aRequestParameters = new HashMap <String, String []>
(); aRequestParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aRequestParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aRequestParameters.put ("x-axw-rest-identifier", new String [] {sIdentifier});
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 161/181
final String sSecurityToken = getSecurityToken (sSecret,
aRequestParameters);
aMethod.addHeader ("x-axw-rest-token", sSecurityToken);
final CloseableHttpResponse aResponse = aClient.execute (aMethod); try {
System.out.println ("Response From RESTful service: \n" + EntityUtils.toString (aResponse.getEntity (), “UTF-8”));
} finally {
aResponse.close (); } }
private static String getSecurityToken (final String sSecret,
final Map <String, String []> aDataMap) throws UnsupportedEncodingException,
NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException
{ final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) {
aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) {
aAllParams.add (sValue); }
} aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) {
aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) {
Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512);
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 162/181
aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) {
nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) {
for (final byte aByte : aEntry) {
aAllParamsArray[nCount] = aByte; nCount++;
} } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8");
} } Running this example should provide a response similar to the following:
Response From RESTful service: Authorized Access Granted @ Mon Feb 10 16:54:40 CET 2014
Necessary Libraries:
The following libraries are required for this sample implementation:
• httpcore and httpclient: https://hc.apache.org/downloads.cgi • commons-logging: https://commons.apache.org/proper/commons-
logging/download_logging.cgi • commons-codec: https://commons.apache.org/proper/commons-
codec/download_codec.cgi • bcprov-jdk: https://www.bouncycastle.org/latest_releases.html
15.3 Sample Implementation (Java): Using HTTP POST
The examples so far showed how to access RESTful services using HTTP GET. Very often (usually when data needs to manipulated using a RESTful service), access is made using HTTP POST. In this case, the parameters sent with the request will not be part of the service URL but rather transported inside a form with the request.
The following code shows a simplified example of how to achieve this. In this example it is assumed that a service is available at
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 163/181
http://localhost:8080/ADOxxWeb/rest/hello which can handle HTTP POST requests and requires the parameter “hello_param”: final HttpPost aMethod = new HttpPost ("http://localhost:8080/ADOxxWeb/rest/hello"); ... // Add headers here final List <NameValuePair> aPostForm = new ArrayList <NameValuePair> (); aPostForm.add (new BasicNameValuePair ("hello_param", "RESTClient")); final Map <String, String []> aRequestParameters = new HashMap <String, String []> (); for (final NameValuePair aEntry : aDataEntries) {
aRequestParameters.put (aEntry.getName (), new String [] {aEntry.getValue ()}); } ... // Add Request parameters here aMethod.setEntity (new UrlEncodedFormEntity (aPostForm)); final String sSecurityToken = getSecurityToken (sSecret, aRequestParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken);
... // Execute request and print out response here
15.4 Sample Implementation (Java): Using HTTP POST to Create a New User
The following code shows how to create a user using HTTP POST: import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64;
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 164/181
import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientPOSTUser { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace the path to your ADO* installation final String sPath = "http://HOST:8080/ADOXX/rest/2.0/users"; final StringBuilder aUserParams = new StringBuilder (); aUserParams.append ("{"); aUserParams.append ("\"loginName\":\"MyUser\","); aUserParams.append ("\"password\":\"Password123++\""); aUserParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); final HttpPost aMethod = new HttpPost (sPath); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey});
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 165/181
// Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final StringEntity aJSON = new StringEntity (aUserParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); System.out.println ("Sending request to: " + sPath); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator);
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 166/181
for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }
15.5 Sample Implementation (Java): Using HTTP GET to Get Model Data
The following is a basic example of accessing the name and description of a model with the specified ID using a small Java program. import java.io.IOException; import java.io.UnsupportedEncodingException; import java.net.URLEncoder; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.AbstractMap; import java.util.ArrayList;
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 167/181
import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientGetModelData { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with the ID of your repository final String sRepoID = "e1fd8ab4-8a4d-4c6f-969c-b300127db1e6"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the ID of the model for which you want to get data final String sModelID = "4cdb6947-1b8b-49c2-9a87-ab5326f7c166"; // Replace the path to your ADO* installation String sPath = "http://HOST:8080/ADOXX/rest/2.0/repos/" + sRepoID + "/models/" + sModelID + "?"; final Map <String, String []> aTokenParameters = new HashMap <String, String []> ();
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 168/181
final List <Entry <String, String>> aRequestParameters = new ArrayList <Map.Entry <String, String>> (); aRequestParameters.add (new AbstractMap.SimpleEntry <> ("attribute", "NAME")); aRequestParameters.add (new AbstractMap.SimpleEntry <> ("attribute", "A_DESCRIPTION")); // Iterate through the search parameters and construct the URL for (final Entry <String, String> aParam : aRequestParameters) { final String sParamName = aParam.getKey (); final String sParamValue = aParam.getValue (); sPath += sParamName + "=" + URLEncoder.encode (sParamValue, "UTF-8") + "&"; // Add the parameter name and the parameter value to the map containing the parameters for the // token generation final String [] aValues = aTokenParameters.get (sParamName); if (aValues == null) { aTokenParameters.put (sParamName, new String [] {sParamValue}); } else { final String [] aNewValues = new String [aValues.length + 1]; for (int i = 0; i < aValues.length; ++i) { aNewValues[i] = aValues[i]; } aNewValues[aNewValues.length - 1] = sParamValue; aTokenParameters.put (sParamName, aNewValues); } } final HttpGet aMethod = new HttpGet (sPath); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey}); // Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en");
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 169/181
System.out.println ("Sending request to: " + sPath); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); final String sResult = EntityUtils.toString (aResponse.getEntity (), "UTF-8"); System.out.println ("Response from RESTful service: " + sResult); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ());
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 170/181
} final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }
15.6 Sample Implementation (Java): Using HTTP POST to Create a New Object
The following code shows how to create a new object using HTTP POST. The object is created in the repository with the passed ID and the passed attributes contained in the variable aCreationParams are set. Replace repository ID, key, secret, classname and attribute names and values with data fitting your scenario. package Write; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac;
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 171/181
import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientCreateObject { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with the ID of your repository final String sRepoID = "a800755e-c679-4a03-84c7-2e9eee86de42"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the path to your ADO* installation final String sPath = "http://HOST:8080/ADOXX/rest/2.0/repos/" + sRepoID + "/objects"; final StringBuilder aCreationParams = new StringBuilder (); aCreationParams.append ("{"); aCreationParams.append ("\"name\":\"New Object\","); // Replace C_CLASSNAME with the name of your class aCreationParams.append ("\"metaName\":\"C_CLASSNAME\","); aCreationParams.append ("\"attributes\":"); aCreationParams.append ("["); aCreationParams.append ("{"); // Replace A_STRING_ATTR with the name of your attribute aCreationParams.append ("\"metaName\":\"A_STRING_ATTR\","); aCreationParams.append ("\"value\":\"New Value\""); aCreationParams.append ("},"); aCreationParams.append ("{"); // Replace A_BOOLEAN_ATTR with the name of your attribute aCreationParams.append ("\"metaName\":\"A_BOOLEAN_ATTR\","); aCreationParams.append ("\"value\":true");
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 172/181
aCreationParams.append ("}"); aCreationParams.append ("]"); aCreationParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); final HttpPost aMethod = new HttpPost (sPath); final StringEntity aJSON = new StringEntity (aCreationParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); System.out.println ("Sending request to: " + sPath); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey}); // Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret,
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 173/181
final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray);
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 174/181
return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }
15.7 Sample Implementation (Java): Using HTTP PATCH to Update an Existing Object
The following code shows how to update an existing object using HTTP PATCH. The object is identified by the ID provided in the request URL and the attributes passed in the variable aUpdateParams are set. Replace repository ID, object ID, key, secret, attribute name and value with data fitting your scenario. package Write; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security; import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPatch; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientUpdateObject { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault ();
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 175/181
// Replace with the ID of your repository final String sRepoID = "a800755e-c679-4a03-84c7-2e9eee86de42"; // Replace with the ID of the object you want to update final String sObjectID = "3f6e11e4-fb53-408f-b2dd-1dc6c1d68ca2"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the path to your ADO* installation final String sPath = "http://HOST:8080/ADOXX/rest/2.0/repos/" + sRepoID + "/objects/" + sObjectID; final StringBuilder aUpdateParams = new StringBuilder (); aUpdateParams.append ("{"); aUpdateParams.append ("\"attributes\":"); aUpdateParams.append ("["); aUpdateParams.append ("{"); // Replace A_STRING_ATTR with the name of your attribute aUpdateParams.append ("\"metaName\":\"A_STRING_ATTR\","); aUpdateParams.append ("\"value\":\"Updated Value\""); aUpdateParams.append ("}"); aUpdateParams.append ("]"); aUpdateParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); System.out.println (sPath); final HttpPatch aMethod = new HttpPatch (sPath); final StringEntity aJSON = new StringEntity (aUpdateParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey});
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 176/181
// Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally { aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); }
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 177/181
final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry) { aAllParamsArray[nCount] = aByte; ++nCount; } } final byte [] aResult = aHmac.doFinal (aAllParamsArray); return new String (Base64.encodeBase64 (aResult), "UTF-8"); } }
15.8 Sample Implementation (Java): Using HTTP POST to create a Relation between two Existing Objects
The following code shows how to create a relation between two existing objects using HTTP POST. The first object is identified by the ID provided in the request URL, the relation direction is identified by the keyword "outgoing" in the request URL and the relation class is identified by the relation class name within the request URL. The ID of the second object is contained as "toId" in the variable aRelationParams. Replace repository ID, object ID, toId, relation class, relation direction, key and secret with data fitting your scenario. package Write; import java.io.IOException; import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import java.security.Security;
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 178/181
import java.text.Collator; import java.util.ArrayList; import java.util.Collections; import java.util.Date; import java.util.HashMap; import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Map.Entry; import java.util.UUID; import javax.crypto.Mac; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; import org.apache.http.client.ClientProtocolException; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.entity.ContentType; import org.apache.http.entity.StringEntity; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.bouncycastle.jce.provider.BouncyCastleProvider; public class StandardRESTfulServicesClientCreateRelation { public static void main (final String [] args) throws ClientProtocolException, IOException, InvalidKeyException, NoSuchAlgorithmException, NoSuchProviderException { final CloseableHttpClient aClient = HttpClients.createDefault (); // Replace with the ID of your repository final String sRepoID = "a800755e-c679-4a03-84c7-2e9eee86de42"; // Replace with the ID of the object you want to update final String sObjectID = "3f6e11e4-fb53-408f-b2dd-1dc6c1d68ca2"; // Replace with the name of the relation class of which you want to create a relation final String sRelClassName = "RC_REL_CLASS_NAME"; // Replace with your key final String sKey = "boc.rest.key.mfb.StandardRESTfulServices"; // Replace with your secret final String sSecret = "d4514a20-0913-4940-8403-f1f58d9fdba8e25bfb85-6066-4449-8970-d1556f126bfa741e2dec-765e-425f-92c7-2a9aef45ea594e947521-1ed7-4773-a244-f75957b5041ec73e334e-37db-4df0-8554-452b1d72208d0e002d92-1451-4513-ab6a-661952c64b8a69b5bb42-0bea-4905-926b-e1ec04e2912369998e61-a355-4f60-a86f-790af5ac4d4cf3d70a24-be75-4168-808c-94fa42d27be065c0e536-7272-48e0-9091-aea9b54ac34aff28734b-14b8-4ffb-99c5-2f28e1fff8ee2d2e01ca-d7b9-4a21-a5ce-0edd9dca9dc9f9986081-3496-4603-bc78-df27635d4c395761a988-9ca0-497c-920e-8621b393db46c166c5b8"; // Replace with the path to your ADO* installation final String sPath = "http://HOST:8000/ADOXX/rest/2.0/repos/" + sRepoID +
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 179/181
"/objects/" + sObjectID + "/relations/outgoing/" + sRelClassName; final StringBuilder aRelationParams = new StringBuilder (); aRelationParams.append ("{"); // Replace with the ID of the object you want to create a relation to aRelationParams.append ("\"toId\":\"{f1cb2932-05dc-44e0-a5dc-fe5d4f6e3795}\""); aRelationParams.append ("}"); final Map <String, String []> aTokenParameters = new HashMap <String, String []> (); final HttpPost aMethod = new HttpPost (sPath); final StringEntity aJSON = new StringEntity (aRelationParams.toString (), ContentType.APPLICATION_JSON); aMethod.setEntity (aJSON); final long nDate = new Date ().getTime (); final String sDate = String.valueOf (nDate); final String sGUID = UUID.randomUUID ().toString (); aMethod.addHeader ("x-axw-rest-identifier", sKey); aMethod.addHeader ("x-axw-rest-timestamp", sDate); aMethod.addHeader ("x-axw-rest-guid", sGUID); aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate}); aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID}); aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey}); // Construct the token final String sSecurityToken = createSecurityToken (sSecret, aTokenParameters); aMethod.addHeader ("x-axw-rest-token", sSecurityToken); // The headers controlling the return type and the language do not have to be considered for // token generation aMethod.addHeader ("Accept", "application/json"); aMethod.addHeader ("Accept-Language", "en"); final CloseableHttpResponse aResponse = aClient.execute (aMethod); try { System.out.println ("Request Status Code: " + aResponse.getStatusLine ().getStatusCode ()); } catch (final Exception aEx) { aEx.printStackTrace (); } finally
BOC Management Office RESTful Services
Author: BOC Group
© 2019, BOC Group Page 180/181
{ aResponse.close (); } } private static String createSecurityToken (final String sSecret, final Map <String, String []> aDataMap) throws UnsupportedEncodingException, NoSuchProviderException, NoSuchAlgorithmException, InvalidKeyException { final List <byte []> aContent = new ArrayList <byte []> (); final List <String> aAllParams = new ArrayList <String> (); for (final Entry <String, String []> aEntry : aDataMap.entrySet ()) { aAllParams.add (aEntry.getKey ()); for (final String sValue : aEntry.getValue ()) { aAllParams.add (sValue); } } aAllParams.add (sSecret); final Collator aCollator = Collator.getInstance (Locale.US); Collections.sort (aAllParams, aCollator); for (final String aEntry : aAllParams) { aContent.add (aEntry.getBytes ("UTF-8")); } final String PROVIDER_BOUNCYCASTLE = "BC"; final String SHA512 = "HMac/SHA512"; if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null) { Security.addProvider (new BouncyCastleProvider ()); } final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE); final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512); aHmac.init (aKey); aHmac.reset (); int nSize = 0; for (final byte [] aEntry : aContent) { nSize += aEntry.length; } final byte [] aAllParamsArray = new byte [nSize]; int nCount = 0; for (final byte [] aEntry : aContent) { for (final byte aByte : aEntry)