{ "openapi": "3.0.2", "info": { "title": "Entitlement Directory Service", "version": "0.0.3", "description": "A directory service for application entitlements.\n\nThe purpose of the service is to provide a data model to \nallow lookup the location (URL o file) for the entitlement\nassociated with the application and tenant." }, "paths": { "/service/directory/{application_id}": { "summary": "Fetch Entitlements Service Directory", "description": "Retrieve a list of entitlement services\nfor the application. This wil be generally\na single tenant.", "get": { "tags": [ "Draft" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/services-model" }, "examples": { "sampleA": { "value": "\n {\n \"entitlement\": {\n \"checkList\": [\n {\n \"tenant\": \"1k\",\n \"url\": \"apo\",\n \"interfaceType\": \"formatA\",\n \"digitalId\": \"l\",\n \"organisation\": \"6\",\n \"interfaceMethod\": \"POST\"\n },\n {\n \"tenant\": \"vb\",\n \"url\": \"ypn8ql\",\n \"interfaceType\": \"formatA\",\n \"digitalId\": \"\",\n \"organisation\": \"rj\",\n \"interfaceMethod\": \"POST\"\n }\n ]\n },\n \"applicationId\": \"\"\n }\n" } } } }, "description": "A list of services" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" } } }, "description": "Request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" } } }, "description": "Unauthorised request" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" }, "examples": { "health500error": { "value": { "status": "some text", "message": "some text", "resolution": "some text", "technical": "some text" } } } } }, "description": "Internal error with service, with minimal\ninformation available" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" }, "examples": { "ealth503error": { "value": { "status": "FAIL", "version": "some text", "notes": [ "some text", "some text" ], "output": "some text", "description": "some text", "checks": { }, "release_id": "some text", "service_id": "some text", "links": [ { "href": "some text", "rel": "some text", "operation": "GET", "caption": "some text", "media_type": "some text" }, { "href": "some text", "rel": "some text", "operation": "DELETE", "caption": "some text", "media_type": "some text" } ] } } } } }, "description": "The service is unavailable" } }, "security": [ { } ], "operationId": "getServiceDirectoryList", "summary": "Fetch Entitlements Service Directory", "description": "Retrieve a list of entitlement services" }, "parameters": [ { "name": "application_id", "description": "An application identity that the entitlements service supports.", "schema": { "type": "string" }, "in": "path", "required": true } ] }, "/healthcheck": { "summary": "Health service", "description": "This service end point is to discover the health of the\nservice. The information provides an overall health\nand also health individual upstream dependencies.\n\n# Security\n\nThe service is secured to stop abuse.", "get": { "tags": [ "Draft", "ManageService" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/health-model" }, "examples": { "Simple-health": { "value": { "status": "PASS", "version": "some text", "notes": [ "some text", "some text" ], "output": "some text", "description": "some text", "checks": { }, "release_id": "some text", "service_id": "some text", "links": [ { "href": "some text", "rel": "some text", "operation": "PUT", "caption": "some text", "media_type": "some text" }, { "href": "some text", "rel": "some text", "operation": "POST", "caption": "some text", "media_type": "some text" } ] } } } } }, "description": "The service is healthy" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" } } }, "description": "Request is not valid" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" } } }, "description": "Unauthorised request" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" }, "examples": { "health500error": { "value": { "status": "some text", "message": "some text", "resolution": "some text", "technical": "some text" } } } } }, "description": "Internal error with service, with minimal\ninformation available" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/health-model" }, "examples": { "ealth503error": { "value": { "status": "FAIL", "version": "some text", "notes": [ "some text", "some text" ], "output": "some text", "description": "some text", "checks": { }, "release_id": "some text", "service_id": "some text", "links": [ { "href": "some text", "rel": "some text", "operation": "GET", "caption": "some text", "media_type": "some text" }, { "href": "some text", "rel": "some text", "operation": "DELETE", "caption": "some text", "media_type": "some text" } ] } } } } }, "description": "The service is unavailable" } }, "security": [ { "OAuth": [ ] } ], "operationId": "gethealth", "summary": "Retrieve the health of the service", "description": "Gets the health of the service" } }, "/service/directory/{application_id}/{tenant_id}": { "summary": "Fetch Entitlements Service Directory", "description": "Retrieve a single entitlement services\nwhich is the requested application and tenant.", "get": { "tags": [ "Draft" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/directory-model" }, "examples": { "sampleA": { "value": "\n {\n \"entitlement\": {\n \"checkList\": [\n {\n \"tenant\": \"1k\",\n \"url\": \"apo\",\n \"interfaceType\": \"formatA\",\n \"digitalId\": \"l\",\n \"organisation\": \"6\",\n \"interfaceMethod\": \"POST\"\n },\n {\n \"tenant\": \"vb\",\n \"url\": \"ypn8ql\",\n \"interfaceType\": \"formatA\",\n \"digitalId\": \"\",\n \"organisation\": \"rj\",\n \"interfaceMethod\": \"POST\"\n }\n ]\n },\n \"applicationId\": \"\"\n }\n" } } } }, "description": "A service" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" } } }, "description": "Request is not valid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" } } }, "description": "Unauthorised request" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" }, "examples": { "health500error": { "value": { "status": "some text", "message": "some text", "resolution": "some text", "technical": "some text" } } } } }, "description": "Internal error with service, with minimal\ninformation available" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-model" }, "examples": { "ealth503error": { "value": { "status": "FAIL", "version": "some text", "notes": [ "some text", "some text" ], "output": "some text", "description": "some text", "checks": { }, "release_id": "some text", "service_id": "some text", "links": [ { "href": "some text", "rel": "some text", "operation": "GET", "caption": "some text", "media_type": "some text" }, { "href": "some text", "rel": "some text", "operation": "DELETE", "caption": "some text", "media_type": "some text" } ] } } } } }, "description": "The service is unavailable" } }, "security": [ { } ], "operationId": "getServiceDirectory", "summary": "Fetch Entitlements Service Directory", "description": "Retrieve a single entitlement services" }, "parameters": [ { "name": "application_id", "description": "An application identity that the entitlements service supports.", "schema": { "type": "string" }, "in": "path", "required": true }, { "name": "tenant_id", "schema": { "type": "string" }, "in": "path", "required": true } ] } }, "components": { "schemas": { "error-model": { "description": "A common error payload returned \nwhen the response code is not 2xx", "type": "object", "properties": { "status": { "description": "Status identifier that can be used to identify the\ncause of the error.\n\nIt s not the HTTP status code (eg 4xx ot 5xx)", "type": "string" }, "message": { "description": "Error description, that shuld be less technical \nand more user orientated where possible", "type": "string" }, "resolution": { "description": "Information on how the error or issue may\nbe resolved.", "type": "string" }, "technical": { "description": "Technical information for the error.\n\nThis must not contain sensitive information", "type": "string" } } }, "directory-model": { "description": "An entry for the directory giving information about the\nentitlement service epxosed by the tenant application.", "required": [ "tenant", "url", "interface_type" ], "type": "object", "properties": { "tenant": { "description": "A unique identifier such as GUID for the tenant", "type": "string" }, "url": { "description": "URL for the tenant application entitlement service.", "type": "string" }, "interfaceType": { "description": "The interface contract exposed by the tenant application", "enum": [ "PingAuthorise", "formatA", "formatB" ], "type": "string" }, "digitalId": { "description": "The portal user identifier attribute name", "type": "string" }, "organisation": { "description": "Organisation attribute name.\n\nFor example:\n\nX-Organisation", "type": "string" }, "interfaceMethod": { "description": "The HTTP method to use.", "enum": [ "GET", "POST" ], "type": "string" } }, "example": { "tenant": "rm1iw33", "url": "https://x.example.com/app3/entitlements", "interfaceType": "formatA", "digitalId": "X898989", "organisation": "Acme", "interfaceMethod": "GET" } }, "entitlement-model": { "description": "", "type": "object", "properties": { "checkList": { "description": "List of entitlement services", "type": "array", "items": { "$ref": "#/components/schemas/directory-model" } } }, "example": { "checkList": [ { "tenant": "x", "url": "https://xxx.example.com/entitlements/app12", "interfaceType": "formatA", "digitalId": "", "organisation": "", "interfaceMethod": "POST" }, { "tenant": "iq", "url": "https://app13.example.com/service/entitlements", "digitalId": "s", "organisation": "c67ka", "interfaceMethod": "GET" } ] } }, "services-model": { "description": "", "required": [ "entitlement", "application_id" ], "type": "object", "properties": { "entitlement": { "$ref": "#/components/schemas/entitlement-model", "description": "Entitlement service details" }, "applicationId": { "description": "Application Identifier", "type": "string" } }, "example": { "entitlement": { "checkList": [ { "tenant": "qy", "url": "", "interfaceType": "formatA", "digitalId": "", "organisation": "m", "interfaceMethod": "POST" }, { "tenant": "", "url": "e", "interfaceType": "PingAuthorise", "digitalId": "", "organisation": "r", "interfaceMethod": "GET" } ] }, "applicationId": "k" } }, "health-model": { "title": "Root Type for health-model", "description": "The response object from a \"health\" request.\n\nThe response may be full. partial, minimal or missing \nif the statsu is not \"200\"", "required": [ "status", "checks", "links" ], "type": "object", "properties": { "status": { "description": " Indicates whether the service status is acceptable\r\n or not\r\n \r\n indicates whether the service status is acceptable\r\n or not. API publishers SHOULD use following values for the field:\r\n\r\n* \"pass\": healthy (acceptable aliases: \"ok\" to support Node's\r\n Terminus and \"up\" for Java's SpringBoot),\r\n\r\n* \"fail\": unhealthy (acceptable aliases: \"error\" to support Node's\r\n Terminus and \"down\" for Java's SpringBoot), and\r\n\r\n* \"warn\": healthy, with some concerns.\r\n\r\n The value of the status field is case-insensitive and is tightly\r\n related with the HTTP response code returned by the health endpoint.\r\n For \"pass\" status, HTTP response code in the 2xx-3xx range MUST be\r\n used. For \"fail\" status, HTTP response code in the 4xx-5xx range\r\n MUST be used. In case of the \"warn\" status, endpoints MUST return\r\n HTTP status in the 2xx-3xx range, and additional information SHOULD\r\n be provided, utilizing optional fields of the response.\r\n\r\n A health endpoint is only meaningful in the context of the component\r\n it indicates the health of. It has no other meaning or purpose. As\r\n such, its health is a conduit to the health of the component.\r\n Clients SHOULD assume that the HTTP response code returned by the\r\n health endpoint is applicable to the entire component (e.g. a larger\r\n API or a microservice). This is compatible with the behavior that\r\n current infrastructural tooling expects: load-balancers, service\r\n discoveries and others, utilizing health-checks.", "enum": [ "PASS", "WARN", "FAIL" ], "type": "string" }, "version": { "description": "Public version of the service", "type": "string" }, "notes": { "description": "Array of notes relevant to current state of health", "type": "array", "items": { "type": "string" } }, "output": { "description": "Raw error output, in case of \"fail\" or \"warn\"\r\nstates. This field SHOULD be omitted for \"pass\" state.", "type": "string" }, "description": { "description": "A human-friendly description of the\r\nservice.\r\n", "type": "string" }, "checks": { "description": " The \"checks\" object MAY have a number of unique keys, one for each\r\n logical downstream dependency or sub-component. Since each sub-\r\n component may be backed by several nodes with varying health\r\n statuses, these keys point to arrays of objects. In case of a\r\n single-node sub-component (or if presence of nodes is not relevant),\r\n a single-element array SHOULD be used as the value, for consistency.\r\n\r\n The key identifying an element in the object SHOULD be a unique\r\n string within the details section. It MAY have two parts:\r\n \"{componentName}:{measurementName}\", in which case the meaning of the\r\n parts SHOULD be as follows:\r\n\r\n * componentName: (optional) human-readable name for the component.\r\n MUST not contain a colon, in the name, since colon is used as a\r\n separator.\r\n\r\n * measurementName: (optional) name of the measurement type (a data\r\n point type) that the status is reported for. MUST not contain a\r\n colon, in the name, since colon is used as a separator. The\r\n observation's name can be one of:\r\n\r\n - A pre-defined value from this spec. Pre-defined values\r\n include:\r\n\r\n o utilization\r\n\r\n o responseTime\r\n\r\n o connections\r\n\r\n o uptime\r\n\r\n - A common and standard term from a well-known source such as\r\n schema.org, IANA or microformats.\r\n\r\n - A URI that indicates extra semantics and processing rules that\r\n MAY be provided by a resource at the other end of the URI.\r\n URIs do not have to be dereferenceable, however. They are just\r\n a namespace, and the meaning of a namespace CAN be provided by\r\n any convenient means (e.g. publishing an RFC, Open API Spec\r\n document or a nicely printed book).\r\n\r\n On the value side of the equation, each \"component details\" object in\r\n the array SHOULD have at least one key.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/healthCheck-model" } } }, "releaseId": { "description": "In well-designed APIs, backwards-compatible\r\nchanges in the service should not update a version number. APIs\r\nusually change their version number as infrequently as possible, to\r\npreserve stable interface. However, implementation of an API may\r\nchange much more frequently, which leads to the importance of having\r\nseparate \"release number\" or \"releaseId\" that is different from the\r\npublic version of the API.", "type": "string" }, "serviceId": { "description": "A unique identifier (UUID) for the service", "type": "string" }, "links": { "description": "Links to additional information or actions for the resource", "type": "array", "items": { "$ref": "#/components/schemas/links-model" } } }, "example": { "status": "PASS", "version": "2", "notes": [ "6", "yb" ], "output": "", "description": "", "checks": { }, "releaseId": "xv", "serviceId": "bb", "links": [ { "href": "", "rel": "8f", "operation": "PUT", "caption": "", "media_type": "r" }, { "href": "2dy", "rel": "4wq2rld", "operation": "PUT", "caption": "8a", "media_type": "" } ] } }, "healthCheck-model": { "title": "Root Type for healthcheck-model", "description": "", "type": "object", "properties": { "status": { "type": "string" }, "output": { "type": "string" }, "affected_end_points": { "type": "array", "items": { "type": "string" } }, "componentId": { "type": "string" }, "componentType": { "type": "string" }, "observedUnit": { "type": "string" }, "observedValue": { "format": "float", "type": "number" }, "asAt": { "format": "date-time", "description": "\nThe value is in ISO 8601 format\n\nhttps://www.iso.org/iso-8601-date-and-time-format.html", "type": "string" } }, "example": { "status": "v1p", "output": "5f4l9g8", "affected_end_points": [ "t22i", "" ], "componentId": "", "componentType": "37yy", "observedUnit": "t1a", "observedValue": 73.05, "asAt": "2018-02-10T09:30Z" } }, "links-model": { "title": "Root Type for links-model", "description": "Hypermedia links see https://restfulapi.net/hateoas/ \n", "required": [ "rel", "href" ], "type": "object", "properties": { "href": { "type": "string" }, "rel": { "description": "The relationships for the resource as hypermedia link.\n\nThe common values are:\n\n* self : this resource. Normally used in lists,\n* first : the first resource in a list, \n* last : the last resource in a list, \n* next : the next resource or page in a list, \n* prev : the previous resource or page in a list\n* parent: the parent resource for the item\n* parent+collection: the list of children of the parent resource\n* collection: list of children of the resource\n* buy: link to purchase the investment\n* sell: link to sell the invetsment, assuming the investor has holdings\n* quote: link to quote for the asset\n* icon : URL to the icon for the resource\n* video : URL to a video\n* external : URL to external content\n* content : inline (HTML or markdonw) content related to the resource\n* price : link to resource (product) unit price\n* price+collection : link to list of historical unit prices\n \nThe \"rel\" value is also dependent on context. There is no prices or ability to buy/sell marketplace itself and therefore these resources will not provide a \"buy\" link for instance.\n\nA buy/sell link are expected to be POST requests and therefore the \"operation\" will need to be considered. If perdforming a \"POST\" then the caller will need to know the JSON model for the POST, if the media type is \"application/json\" as an example.", "type": "string" }, "operation": { "description": "The operation that the service resource accepts.\n\nCommonly this will be a GET or POST", "enum": [ "GET", "POST", "DELETE", "PUT", "PATCH", "HEAD" ], "type": "string" }, "caption": { "description": "A caption that can be displaye dfor the link", "type": "string" }, "mediaType": { "description": "The type of resource media type that the link refers to.\n\nExamples are:\n\n* application/json\n* text/html", "type": "string" } }, "example": { "href": "", "rel": "", "operation": "PUT", "caption": "", "mediaType": "l" } } }, "securitySchemes": { "OAuth": { "flows": { }, "type": "oauth2" } } }, "tags": [ { "name": "Draft", "description": "A service definition in the early stages of design" }, { "name": "Proposed", "description": "A service definition that has been drafted and\nis being discussed." }, { "name": "Published", "description": "A service definition that has been accepted\nand is being used in production or ready\nfor production use." } ] }