Tribestream API Registry

Tribestream API Registry

Development

To build and run the registry in its own TomEE instance:

$ mvn clean package -DskipTests tomee-embedded:run -pl :tribestream-api-registry-webapp

To make TomEE pick up changes to any static resources, typescript files, templates or style sheets:

$ cd tribestream-api-registry-webapp
$ mvn frontend:npm@dev

Note that you can run elasticsearch with the dedicated plugin:

cd tribestream-api-registry-webapp && mvn elasticsearch:run

If you do so, ensure to skip the automatically launched one adding as system property: -Ddev.elasticsearch=skip.

API

The client uses these endpoints:

Get a single application by id:

GET http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c

{
  "swagger":{
    "swagger":"2.0",
    "paths": {
      "/pets/{id}": {
        "get": {
          "description": "..." (1)
      }
    },
  }
}

1. The paths are reduced so that the operations only contain the properties summary and description All other properties of an endpoint must be retrieved via the endpoint below.

Links are communicated in the vendor extension x-tribestream-api-registry:

Link: <http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c>;rel="self"
Link: <http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c/endpoint/f27efad1-a6a2-4066-af4e-b50a0194f46a>;rel="GET /pets"
{
  "swagger":{
    "swagger":"2.0",
    "paths": {
      "/pets/{id}": {
        "get": {
          "description": "..." (1)
      }
    },
    "x-tribestream-api-registry": {
      "links": [
        {
          "rel": "self",
          "href": "http://localhost:8080/registry/api/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863"
        },
        {
          "rel": "history",
          "href": "http://localhost:8080/registry/api/history/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863"
        },
        {
          "rel": "endpoints",
          "href": "http://localhost:8080/registry/api/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863/endpoint"
        },
        {
          "rel": "GET /pets/{id}",
          "href": "http://localhost:8080/registry/api/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863/endpoint/28631ade-1baf-4013-9e9e-86e48874315f"
        }
      ]
    }
  }
}

Get an endpoint of an application:

GET http://localhost:8080/registry/api/application/{applicationId}/endpoint/{endpointId}

{
  "httpMethod":"get",
  "path":"/workNotifications/{region}/{function}",
  "operation":{
    "description":"....",
    "consumes":["application/xml"],
    "produces":["application/xml"],
    ...
  }
}

Links for the endpoint point to the endpoint itself, its history and the application:

{
  "httpMethod":"get",
  "path":"/workNotifications/{region}/{function}",
  "operation":{
    "description":"....",
    "consumes":["application/xml"],
    "produces":["application/xml"],
    ...
    "x-tribestream-api-registry": {
      "links": [
        {
          "rel": "self",
          "href": "http://localhost:8080/registry/api/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863/endpoint/28631ade-1baf-4013-9e9e-86e48874315f"
        },
        {
          "rel": "history",
          "href": "http://localhost:8080/registry/api/history/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863/endpoint/28631ade-1baf-4013-9e9e-86e48874315f"
        },
        {
          "rel": "application",
          "href": "http://localhost:8080/registry/api/application/6f80ede5-5cd9-4c5a-aeb7-5cb3fb57f863"
        }
      ]
    }
  }
}

Import an application:

POST http://localhost:8080/registry/api/application/
{
  "swagger":{
    "swagger":"2.0",
    "paths": {
      "/pets/{id}": {
        "get": {
          "description": "...",
          "params": []
      }
    },
  },
}

{
  "swagger":{
    "swagger":"2.0",
    "paths": {
      "/pets/{id}": {
        "get": {
          "description": "..." (1)
      }
    },
  }
}

1. The paths are reduced so that the operations only contain the properties summary and description All other properties of an endpoint must be retrieved via the endpoint below.

The link for the new application is also communicated in the vendor extension.

Update an application:

PUT http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c
{
  "swagger":{
    "info": {
      "title": "New Petstore"
    }
  }
}

{
  "swagger":{
    "swagger":"2.0",
    "paths": {
      "/pets/{id}": {
        "get": {
          "description": "..." (1)
      }
    },
  },
  "_links":{
    "self":"http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c",
    "GET /pets":"http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c/endpoint/f27efad1-a6a2-4066-af4e-b50a0194f46a"
  }
}

Delete an application:

DELETE http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c

Search endpoints by multiple criteria

GET http://localhost:8080/registry/api/registry
        ?tag=tagA
        &category=catA
        &role=roleA
        &app=myApp
        &page=0
        &count=20

{
  "results":[
    {
      "applicationId":"1b281178-c381-4437-b101-a441ef508e79",
      "endpointId":"518f5b5e-f964-4311-8b47-ad99019a2fa8",
      "application":"Uber API",
      "applicationVersion":"1.0.0",
      "httpMethod":"GET",
      "path":"/estimates/price",
      "description":"Price Estimates",
      "consumes":[],
      "produces":[],
      "secured":false,
      "rateLimited":false,
      "score":2.5073297
    },
  ],
  "applications":[
    {"text":"/v1","weight":2}
  ],
  "categories":[],
  "tags":[
    {"text":"Estimates","weight":2}
  ],
  "roles":[],
  "total":2,
  "current":0}

Create an endpoint

POST http://localhost:8080/registry/api/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c/endpoint
{
  "httpMethod":"get",
  "path":"/workNotifications/{region}/{function}",
  "operation":{
    "description":"....",
    "consumes":["application/xml"],
    "produces":["application/xml"],
    ...
  }
}

The response status will be HTTP 201

{
  "httpMethod":"get",
  "path":"/workNotifications/{region}/{function}",
  "operation":{
    "description":"....",
    "consumes":["application/xml"],
    "produces":["application/xml"],
    ...
  }
}

For applications and endpoints a revision log will be managed. This allows to review past changes.

The revision log for an application is available via the history link that is returned when getting an application or an endpoint. In general the history is available under the history resource:

GET http://localhost:8080/registry/api/history/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c

The response contains a list of revision information:

[
  {
    "revisionId": 9,
    "timestamp": 1474532005121,
    "username": "admin",
    "revisionType": "MOD"
  },
  {
    "revisionId": 7,
    "timestamp": 1474531974419,
    "username": "admin",
    "revisionType": "MOD"
  },
  {
    "revisionId": 1,
    "timestamp": 1474531938316,
    "revisionType": "ADD"
  }
]

The log is sorted by revision id in descending order, that is the latest revisions appear first. Please note that revision ids need not be consecutive!

The timestamp contains the milliseconds since January, 1st 1970.

The revision type can be one of the three strings ADD, MOD or DEL.

The history resource supports pagination. The page to fetch can be specified via the page query parameter. Pages are 1-based, that is the first page is available via the page parameter 1 The page size can be specified via the per_page query parameter. The default page size is 20.

For each revision n presented in the result, the response contains one link revision n. In general the URL will look like this to get revision 7 from the example above:

GET http://localhost:8080/registry/api/history/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c/7

Revision logs for endpoints can be retrieved in a similar fashion:

GET http://localhost:8080/registry/api/history/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c/endpoint/f27efad1-a6a2-4066-af4e-b50a0194f46a

A certain revision of an endpoint can be obtained in a similar way as a historic application:

GET http://localhost:8080/registry/api/history/application/253a25ec-7c2c-4ca5-88f6-9cd115733f7c/endpoint/f27efad1-a6a2-4066-af4e-b50a0194f46a/7

Tribestream API Registry vendor extension

Properties that are not defined as part of the OpenAPI specification are stored in a vendor extension.

Operation extension

{
  "swagger": "2.0",
  "info": {},
  "paths": {
    "pets": {
      "get": {
        "description": "..."
        "x-tribestream-api-registry": {
          "status": "ACCEPTED",
          "categories": ["mammals"],
          "roles": ["roleA", "roleB"],
          "auth-methods": ["HTTP Signatures", "Bearer"],
          "api-versions": "0.1",
          "endpoint-protocol": "https",
          "request-parameters": "```GET /pets\nhost: host.com\nAccept: application/xml```",
          "response-parameters": "```HTTP/1.1 200 OK\nContent-Type: application/xml```",
          "example-response": "```xml<elem>...</elem>```",
          "example-error-response": "```xml<elem>...</elem>```",
          "rates": [
            {
              "rateLimit":2,
              "rateWindow":7,
              "rateUnit":"MINUTES",
              "description":"Two requests in seven minutes."
            }
          ],
          "sees":[
            {"href":"http://swagger.io"},
            {"href":"http://tomitribe.com"}
          ]
        }
      }
    }
  }
}

OAuth2 authentication

The Tribestream API Registry supports authentication via OAuth2 by passing the user credentials to a OAuth2 authorization server. Therefore the connection to the OAuth2 server has to be configured with these properties:

registry.oauth2.authorizationServerUrl

URL of the authorization server. For example: https://myauthhost/user/oauth/token.

registry.oauth2.clientId

A client id used to authenticate the Tribestream API Registry server application if required. For example tribestream-api-registry

registry.oauth2.clientSecret

If the Tribestream API Registry has to authenticate with a client id and a client secret this property contains the secret. For example very_secret!.

registry.oauth2.tlsProtocol The TLS protocol to be used to connect to the OAuth2 server. Possible values are available at Java Cryptography Architecture Standard Algorithm Name Documentation. The default is TLSv1.2.

registry.oauth2.tlsProvider

Configures the name of the Security provider. This could be for example SunJCE.

registry.oauth2.trustStore

File name of a TLS trust store.

registry.oauth2.trustStoreType

The type of the trust store. This could be for example jceks, jks or pkcs12.

To start the Tribestream API Registry with the TomEE Maven plugin that authenticates against your OAuth2 server pass you can pass the above properties to Maven:

mvn tomee:run -pl :tribestream-api-registry-webapp -Dregistry.oauth2.authorizationServerUrl=https://tribe.tomitribe.com/user/oauth/token