Skip to content
logoBack to home screen

Introduction to REST API

Tribefire offers two different REST v2 APIs, which you can try out directly from your browser.

On this page

  1. General
    1. Authentication
  2. CRUD with /rest/v2
    1. URL Endpoints
  3. DDSA with /api/v1
    1. URL Endpoints
  4. REST Parameters and Headers
  5. Collection Properties
  6. Try it Out

General

API EndpointDescription
/rest/v2Allows you to perform create, read, update, delete (CRUD) operations on entities and properties inside accesses. There are different URL endpoints for entities and accesses.
/api/v1Allows you to evaluate service requests.

It is advisable to use the following headers for all REST calls:

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

Authentication

Send a POST call to /api/v1/authenticate for authentication. Make sure to provide your credentials in the body of the request:

ItemDescription
Method and LinkPOST host:port/tribefire-services/api/v1/authenticate
Body{ "user": "cortex", "password": "cortex" }
HeadersContent-Type: application/json

You have to include the session ID in every REST call. You can include it in the following:

  • URL parameter: sessionId=yourSessionId
  • header parameter: gm-session-id

You cannot include the session ID in the body of the request!

If you are not logged in (there is no valid session) and you paste a GET call in your browser, you will be redirected to a login screen. After logging in, you will see the result of your GET call.

The redirect does not happen for the /api/v1/authenticate call.

CRUD with /rest/v2

The /rest/v2 endpoint allows you to perform create, read, update, delete (CRUD) operations on entity instances and properties inside accesses. This endpoint complies as closely as possible with the general REST specifications.

For more information on REST specification, see the following IETF document..

As we comply with the general REST specifications, note the major differences between POST and PUT:

POSTPUT
Works on collectionsWorks on single entities or properties
Allow creation with autogenerated IDCreate or update for a provided ID

If you don't provide an ID, this call fails.
Entity must exist if ID is specifiedEntity doesn't need to exist, it is created with the provided ID if doesn't exist
Updates/creates entities for every callIdempotent (multiple calls with same parameter STRICTLY equivalent to a single call)

URL Endpoints

Within this API, here are the available URL endpoints:

URLDescription
/rest/v2/entities/{accessId}/{typeSignature}/{id}/{partition}Executes a CRUD (i.e. Create, Read, Update or Delete) operation on the given entity or entities in the given access.

The id and partition parameters are optional. The endpoint provides search capabilities.
/rest/v2/properties/{accessId}/{typeSignature}/{id}/{partition}/{property}Executes a CRUD operation on the given property, allows for addition and removal in collection properties.

The id and partition parameters are optional.

We also support SimpleName instead of typeSignature resolution for entities. That means that you can omit the package declaration: my.model.package.MyEntity if there is only one entity with this simple name (the last part of the signature) in the model. If there is more than one entity, a 400 Bad request is thrown.

Here is an overview of all the operations this API offers:

URLGETPOSTPUTDELETEPATCH
/rest/v2/entities/{accessId}/{typeSignature}Entity searchEntity creationEntity update or creationEntity deletionEntity update
/rest/v2/entities/{accessId}/{typeSignature}/{id}/({partition})Entity returnEntity updateEntity update or creationEntity deletionEntity update
/rest/v2/properties/{accessId}/{typeSignature}/{id}/({partition})/{property}Property value returnAddition or removal collection elements

Only works on collection properties		Property value updateProperty value reset to default

int, long, double, float, BigDecimal = 0
Boolean = false
enums, entities, objects = null
maps, lists, sets = empty collection		Property value update

For more information, see REST v2 /rest/v2.

DDSA with /api/v1

The /api/v1 endpoint allows you to execute any DDSA service request.

URL Endpoints

URLDescription
/api/v1/{serviceDomain}/{MyServiceRequestType}Evaluates the service request MyServiceRequest and returns the marshalled response.

This is equivalent to calling MyServiceRequest.eval(evaluator).get() using the JAVA API.

By default, all service requests are mapped to the methods GET, POST, and PATCH.

MethodDescription
GETUsed for simple service requests. All properties are encoded in the URL parameters or as custom (so starting with gm-) headers. The properties must be of type String, int, float, long, double, boolean, Date, decimal, enum or a list or set of the mentioned types.
POSTUsed for more complex service requests. All types are supported. The service request must be encoded in the body of the request, with the mimeType provided in the Content-Type header.
PATCHUsed in the same manner as POST.

For more information, see REST v2 /api/v1.

REST Parameters and Headers

Parameters passed in the URL and in the headers are unmarshalled in different entities that drive the behavior of the REST call.

There are 3 types of parameters that can be unmarshalled:

  • standard headers, e.g. Accept, Content-Type

Standard headers support comma-separated lists: Accept: application/json,application/xml.

  • custom headers, of the form gm-parameterName
  • URL parameters, of the form parameterName

When a request is received by the REST API, it is unmarshalled into 2 entities:

  • one entity for the endpoint that holds configuration for the endpoint, for example: mimeType of the request and supported mime types for the response (with Accept and Content-Type), prettiness of the response or depth of the response
  • one entity for the actual call. For example, the ServiceRequest in the case of the /api/v1 endpoint.

Each entity can be populated from both headers and URL parameters.

If both entities have a property with the same name (for example both a service request and the endpoint for /api/v1 have a depth property) the endpoint property is populated. It is possible to prefix properties to specify which entity should receive the value.

Take a look at the following calls. In terms of result, they are all the same:

  • URL: /api/v1/com.braintribe.model.securityservice.GetCurrentUser?sessionId=xxx&prettiness=high
    Headers:

    • Accept: application/json

  • URL: /api/v1/com.braintribe.model.securityservice.GetCurrentUser?service.sessionId=xxx&endpoint.prettiness=high
    Headers:

    • Accept: application/json

  • URL: /api/v1/com.braintribe.model.securityservice.GetCurrentUser
    Headers:

    • Accept: application/json
    • gm-service.sessionId: xxx
    • gm-endpoint.prettiness: high

  • URL: /api/v1/com.braintribe.model.securityservice.GetCurrentUser?sessionId=xxx
    Headers:

    • Accept: application/json
    • gm-prettiness: high

  • URL: /api/v1/com.braintribe.model.securityservice.GetCurrentUser
    Headers:

    • Accept: application/json
    • gm-sessionId: xxx
    • gm-prettiness: high

Collection Properties

The new REST v2 API allows you to pass collection properties in the URL and as a header. Moreover, when you use the /api/v1 endpoint for service request calls, you can pass collection properties in the body of the request.

  • URL: /api/v1/foo.bar.MyRequest?collectionProperty=xxx&collectionProperty=yyy

  • Header: gm-collectionProperty=xxx gm-collectionProperty=yyy gm-collectionProperty=xxx,yyy

The following patterns are incorrect and will not work:

- /api/v1/foo.bar.MyRequest?collectionProperty=[xxx,yyy]

- /api/v1/foo.bar.MyRequest?collectionProperty=xxx,yyy.

You can only pass a set or array of types below:

  • numbers: integer, long, float, double, decimal
  • Boolean
  • date
  • enum
  • string
  • object (only supported if a there is a TypeSpecification metadata on the property that specializes the type to one of the above types)

You cannot pass another collection as a collection property.

Try it Out

If you want to experiment with the API for yourself, use our integrated Swagger UI.

For more information, see Using Swagger UI.