Using Publication For Capella OSLC API

1. Preamble

This document provides examples that assume that the Publication For Capella server is deployed on http://localhost:8080. Of course, this is not valid in general, especially not in production.

So to transform the examples in something valid for a given deployment of Publication For Capella, the URLs must be transformed by replacing http://localhost:8080 with https://p4c.mycompany.com where p4c.mycompany.com is the actual DNS name of the Publication For Capella server. The port must be included (e.g. https://p4c.mycompany.com:8443 ) if Publication For Capella is deployed on e.g. port 8443 instead of the default 443 HTTPS port.

2. OSLC API

2.1. Logging In

A proper way to login via API has not been implemented yet. Currently the workaround to login to Publication For Capella via API so as to be able to query the contents of published models is to call GET http://localhost:8080/api/graphql and pass the header for Basic Authentication and the header x-perseus-client.

This will return an error response that, if the credentials given in the Basic Authorization header are correct, contains a Set-Cookie header for JSESSIONID that must be set for the next HTTP requests.

Example:

x-perseus-client: true
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

GET http://localhost:8080/api/graphql
--->
Set-Cookie: JSESSIONID=7C2D4DC2F34DFC7E8B2EC00B3481EE7; Path=/; SameSite=None; Secure
Allow: POST
(Additional headers)

(JSON content)

2.2. Model Elements as RDF

Each element of a published model is exposed at a unique and stable URL that is based on:

  • The project ID {project-id};

  • The model ID {model-id};

  • The model object ID {object-id}.

Such a URL can be computed easily as follows: http://localhost:8080/oslc/model/{project-id}/{model-id}/{object-id}.

The model object is provided in RDF format. Publication For Capella supports the following content types: application/rdf+xml, text/turtle, application/xml, text/xml. The desired content type can be requested using the request header Accept.

Example:

Accept: application/rdf+xml

GET http://localhost:8080/oslc/model/fa9644dd-9c17-4b87-82f8-cd72b70f4fa1/35/_QHUAIJY7Ed6rH5SGn-UjSg
RDF is a widespread data format and there are a number of off-the shelf libraries to parse RDF in many programming languages.

2.2.1. Mapping of Capella Model Element EAttributes and EReferences with RDF Properties

Publication For Capella applies a number of rules to map the attributes and references of Capella model elements into their RDF representation.

Table 1. EMF vs RDF Mappings
Capella RDF Query Criterion

identifier

dcterms:identifier

Yes

name (NamedElement)

dcterms:title

Yes

Meta-class name

dcterms:type

Yes

eContainer (parent object)

pers:parent

No

model ID (numeric ID of the model that contains a model object)

pers:modelId

Yes

Any EAttribute attName

pers_mm:attName

Yes

Any EReference refName

pers_mm:refName

Yes

Latest modification date

dcterms:modified

No

These resurces aer all exposed as resources of typ oslc_am:Resource, in compliance with the OSLC Architecture Management vocabulary.

2.3. OSLC Query

Querying the contents of Publication For Capella projects (a project containing zero to many published models) is achieved by performing a HTTP GET request on the project’s OSLC Query URL. This URL is built from the project’s identifier as follows: http://localhost:8080/oslc/model/{project-id}/q? where {project-id} must be replace by the actual project identifier. The query criteria must be added after the question mark of the URL ? and encoded using standard URL query encoding.

For more details on the OSLC query syntax, please refer to the OSLC Query Version 3.0 specification.

The query result is provided in RDF format. Publication For Capella supports the following content types: application/rdf+xml, text/turtle, application/xml, text/xml. The desired content type can be requested using the request header Accept.

Example:

Accept: application/rdf+xml

GET http://localhost:8080/oslc/model/3a94f683-ea4b-4514-8583-3cb688b3da78/q?oslc.where=(...)

Here are some examples of oslc.where clauses for some use-cases:

2.4. Invalid OSLC queries

There are a number of restrictions as to what can be queried, either for security reasons or for technical reasons.

2.4.1. Invalid query across projects

One restriction is that it is not allowed to query data across several projects. Queries a run in the context of a specific project and can only access this project’s data.

Example:

GET http://localhost:8080/oslc/model/3a94f683-ea4b-4514-8583-3cb688b3da78/q?oslc.where=pers_mm%3ArealizedLogicalComponents%3D%3Chttp://localhost:8080/oslc/model/fa9644dd-9c17-4b87-82f8-cd72b70f4fa1/35/_QHUAIJY7Ed6rH5SGn-UjSg%3E

This request (where oslc.where is pers_mm:realizedLogicalComponents=http://localhost:8080/oslc/model/fa9644dd-9c17-4b87-82f8-cd72b70f4fa1/35/_QHUAIJY7Ed6rH5SGn-UjSg) gets rejected.

It is rejected because it is run in the context of project 3a94f683-ea4b-4514-8583-3cb688b3da78 but requests information about a model element located in a different project fa9644dd-9c17-4b87-82f8-cd72b70f4fa1.