Skip to main content

Exploring the API

In order to get up to speed with the REST interface, you can use our interactive API documentation site, which is based on Swagger. This lists the available services and shows samples for their parameters and results. It also allows you to directly invoke the REST endpoints via a simple mouse click:

The fallback content to display on prerendering

In order to use it, go to “https://<your.portal.url>/swagger/ui/index”. The page itself can be opened without logging in.

Authenticating​

Most web services require an OAuth 2.0 bearer token. This is what the server uses to verify that you are indeed authenticated. The user the token belongs to needs the permissions required by the respective endpoint.

If you are signed in to the portal in the same browser, the Swagger UI fills in your access token by itself and reloads the document with it - there is nothing to do. The portal renews its token only while a portal tab is open: if the field stays empty, open the portal once and reload the Swagger UI.

Otherwise, you enter the token once for the whole page:

  1. Paste Bearer <access token> into the field in the top bar, to the right of the document URL (its placeholder reads Bearer <access token>).
  2. Click Explore or press Enter.

The document is reloaded with the token, and every Try it out! sends it in the Authorization header. You can also enter the token with the lock button of a secured operation. To remove the token, clear the field.

How to retrieve the OAuth 2.0 bearer token

Operations and models per content type​

If the token belongs to a tenant user with the permission to view content items, the reloaded document additionally contains a group Content: <contenttypename> for every content type of that tenant, e.g. Content: defect (content type names are used as they are stored, in lowercase). These groups are at the end of the list, in alphabetical order, after the groups ContentItemSync, ContentTypes and ContentItem. Each of them lists the content item operations with the name of the content type already filled in, e.g. GET /api/content/defect, POST /api/content/defect, GET/PUT/PATCH/DELETE /api/content/defect/{id}, POST /api/content/defect/batch and /batchforce, as well as getchanges, export and template/excel.

For exploring and trying out only

Content types can be changed at any time, e.g. by an administrator in the portal. The operations and the model of a content type change with it, without a new API version, so a client built against them can break. Use them to explore the API and to try it out. For integrations, use the generic operations /api/content/{contentTypeName} (see Content Items): they keep their form. Every operation of a Content: <contenttypename> group repeats this warning in its Implementation Notes.

Each of these groups comes with a model <contenttypename>ContentItemDto that lists the fields of an item:

  • the JSON type and format of every field, according to its field type,
  • the allowed values of option fields (as enum),
  • for every reference to another content item, the display text <field>__title (read only),
  • the system fields such as _id, contentItemId, externalId, lastModificationTime, isDeleted and the creator and last modifier.
note
  • Only the title field is listed as required in the model - it is the only field the API enforces. Fields that are marked as required in the content type say so in their description, but an item can be saved without them, and an item read via GET omits the fields that have no value.
  • Fields of the types User and Guid are not part of the JSON of the REST API - neither when reading nor when writing. They are not listed in the model.

The list operation GET /api/content/<contenttypename> takes the OData v3 query options $filter, $orderby, $top and $skip as parameters, so you can try out filtering, sorting and paging. The descriptions of $filter and $orderby list the fields of the content type as they have to be written in a query (first letter in upper case, e.g. Name for the field name), the supported operators and functions, and how to write values. The generic list operation GET /api/content/{contentTypeName} has the same parameters, with a general description.

Without a token, with an invalid or expired token, with the token of a host administrator, or without the permission to view content items, the document only contains the generic operations /api/content/{contentTypeName}, as before. These remain available in any case.