Using Swagger UI

Our implementation of the Swagger UI allows you to use, understand, and try out REST API endpoints of the Tribefire platform.

General

Our Swagger UI implementation helps you understand and try out the REST API endpoints.

The UI allows you to:

• see all available operations on entities, properties and service requests in a given service domain (access)
• see REST API documentation for calls and their parameters
• send REST API calls to various endpoints directly from your browser
• download a Swagger definition file

The REST API is automatically exposed for every deployed model.

For more information, see Model-as-API.

Accessing Swagger UI

You can access the Swagger UI by clicking a link to a specific Swagger endpoint in the Service Domains section on the tribefire services landing page.

You can find the cortex access and the platform setup Swagger endpoints in the Administration section of the landing page. Depending on the link you select, Swagger UI will display different endpoints. You can open the Swagger UI so that it displays all available REST API operations for an access or just a single endpoint, be it an entity type, a property, or a service request.

You can select the following Swagger endpoints:

• CRUD-Entities, which displays CRUD operations on entities
• CRUD-Properties, which displays CRUD operations on properties
• API, which displays service requests

Switching Between Different API Endpoints via URL

Clicking a specific Swagger UI endpoint link on the tribefire services landing page changes the URL. You can use the URL to change the displayed Swagger endpoint but we recommend you use the links found on the landing page.

If you're not logged in and try to access the Swagger endpoint via URL, you will be asked to log in and your session ID will be stored in a cookie. Your subsequent calls from the Swagger UI will use that session ID so you will not have to add it manually to every call.

In the URLs below, it is assumed you are already logged in. Hence, the sessionId=yourSessionId parameter is omitted.

To display different endpoints in the Swagger UI, you change the URL you access the Swagger UI with. By changing the URL you can display the operations on:

• all entities in an access:

  hostname:port/tribefire-services/rest/v2/entities/accessId

  You can also display all properties (/properties/) by changing the /entities/ part of the URL. Also, you can display resources in a given package only by adding the resource=fullyQualifiedName, for example: resource=com.braintribe.user.

• a specific resource in an access, for example com.braintribe.model.user.User:

  hostname:port/tribefire-services/rest/v2/entities/accessId?resource=com.braintribe.model.user.User

  If you don't specify an access but specify a resource, the list will contain all accesses that use the specific resource.

• all properties in an access:

  hostname:port/tribefire-services/rest/v2/properties/accessId

  You can also display the properties for a specific resource by adding the &resource= parameter to the URL, for example &resource=com.braintribe.model.accessapi.

• all service requests in an access:

  hostname:port/tribefire-services/api/v1/accessId

You can also add the enablePartition=true parameter to each URL to trigger the display of the partition parameter in the endpoints.

For more information, see REST v2 Introduction

Swagger UI and Custom tribefire-services Path

If your tribefire-services deployment doesn't have a .war file specific URL subpart you will not be able to access the Swagger UI. To fix this, you must specify the proper path using the TRIBEFIRE_SERVICES_PATH property.

For more information about configuring properties, see Runtime Properties.

Using Swagger UI

When you decide on what to display, the Swagger UI displays the following:

• a list of items of your interest based on the URL you used
• the Models section
• the Swagger JSON file link

List of Items

The list contains REST API endpoints displayed in alphabetical order. The items may be entities, properties, service requests, or accesses, depending on what parameters you passed in the URL. You may notice that you see the HTTP method and a quick description of the call directly in the list.

If you don't see all HTTP operations for a particular resource, it may be that there is metadata attached that prohibit certain operations:

For more information, see Instantiable and NonInstantiable Modifiable and Unmodifiable, and Deletable and NonDeletable

Clicking an entry in the list expands its details. In the details view, you can see every parameter of the respective API call with a detailed description on what the parameter influences.

The description of call parameters is taken from the resource's metamodel. The content you provide as the value of the description attribute of an entity, property, or a service is the one displayed in the corresponding row of the Swagger UI. If you want the descriptions to be more meaningful, the easiest way is to add/change the description parameter in Control Center.

Serialized Request

All properties should be described in Swagger, but serialized-request deserves a separate mention. You can use it to provide a JSON assembly directly to your POST request, instead of filling up all the fields in Swagger separately:

{
    "firstName": "Grzegorz",
    "lastName": "GDPR_was_here"
}

It's important to know that if you need to provide these assemblies on a regular basis in a given request, it may be worth it to create a prototype instead, and map it to that request. For details, see requestPrototyping in Mapping Customization.

Try it Out

When you click on an entry and expand its details, you can click the Try it out button to test the REST call. Clicking this button enables you to fill in all the parameters, execute the query, and inspect the outcome in the Responses section directly in your browser.

If you try out the endpoints for REST calls which require a body to be passed, the body is already pre-populated with the resource's properties and their placeholder values.

When you tried out a REST call and you're satisfied with the result, you can copy the exact URL or Curl you need for this operation from the Responses section.

Models Section

The Models section contains information about every model you can use as a part of the displayed REST API. In the model, you can see the entities and their parameters, with mandatory ones being marked with an asterisk.

JSON File Export

You can export the displayed REST API endpoints by saving the Swagger definition JSON file.

The functionality of importing Swagger files does not come out-of-the-box.

The file contains the entire API definition and is available under the link visible at the top of the page. All you need to do to obtain it is to right-click and select Save As.

Obtaining the file allows you to transfer the models and their REST API definition to another tribefire instance. However, importing a Swagger definition file to another tribefire instance is only possible with the use of the SwaggerModelImportCartridge.

Importing a Swagger Definition File

To set up your instance for Swagger definition import:

1. Download the SwaggerModelImportCartridge, deploy, and synchronize it with your instance.
2. In Control Center, navigate to Custom Deployables, right-click Swagger Import Service Processor and click Deploy.
3. Using the Quick Access box, search for ImportSwaggerModel. Note the following entries that appear in the Service Requests section:

• ImportSwaggerModelFromResource
• ImportSwaggerModelFromUrl

4. Select the proper entry, depending on how you want to import the Swagger definition file. A new tab opens.

5. Depending on the service request you selected, you can see either the swaggerResource or swaggerUrl property. Assign your Swagger definition file or provide a valid link to one and click the Execute button.

   Property	Description
   swaggerResource	The Swagger definition file stored in JSON or YAML. Only available for the ImportSwaggerModelFromResource service request.
   swaggerUrl	Link to the Swagger definition file stored in JSON or YAML. Only available for the ImportSwaggerModelFromUrl service request.

Once the import is successfully completed, a prompt is displayed with the newly created model name.

Definition File Metadata

During the import phase some additional information from the definition file is imported as metadata.

Other than that we have SwaggerExampleMd and SwaggerVendorExtensionMd representing examples and vendor extensions.

For more information about OpenAPI specification, see OpenAPI Specification.

Models Originating from Definitions

Creating a model from an imported definition file actually results in creating two different models: one for the entity types and one for the API definition. The names which tribefire saves the models with are created using the following patterns: