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"}
          ]
        }
      }
    }
  }
}

Configuration

When building the project the configuration is available at tribestream-api-registry-webapp/target/doc/src/configuration.adoc. It is also deployed on central: http://repo1.maven.org/maven2/org/tomitribe/tribestream/tribestream-api-registry-webapp/${version}/tribestream-api-registry-webapp-${version}-configuration.adoc