The details of our Base API Standard including scope, principles, terminology and technical details of the Standard.

Introduction

Evolution and Change

The intent is to evolve this base standard over time as Lloyd's and the Market’s knowledge and experience matures in running, supporting, providing and consuming web services APIs. New updates to the standard specification will contain corrections, additional scope, new features and new guidance.

Scope

APIs that are published to the Market by Lloyd's systems will abide by these standards. Lloyd's systems will use this standard when integrating with other Lloyd's systems. Not every API implemented by Lloyd's is required to abide by this standard.

The following API styles are in scope of the API Standards:

  • Market Participant systems calling a Lloyd's System API
  • Lloyd's Systems calling another Lloyd's System API
  • Synchronous request response interfaces
  • REST interfaces

The following API styles are outside the scope of this standard:

  • Private interfaces within Lloyd's Systems
  • SOAP interfaces
  • Message Originated interfaces
  • Publish Subscribe interfaces
  • Thin client user interfaces (AJAX)

Definition of Terms

Term Definition
Active Directory A range of Microsoft Server and Azure directory-based identity-related services.
API Application Programming Interface.
API Consumer A client program that calls an API.
API Gateway (API-GW) An implementation of the API façade layer. All calls to API Providers from API Consumers pass through the API Gateway.
The API Gateway performs security and other façade functions.
Authentication Validating the identity of a client or service.
Authorisation Verifying that the identity has sufficient privileges to perform an action/operation.
Business Key A business key is a Resource identifier provided by the business context and recognisable by a business user.
CRUD Create Read Update and Delete
The four basic operations that can be performed on an individual record.
Domain-specific language (DSL) A domain-specific language is a computer language specialized to a particular application domain.
HTTP HyperText Transfer Protocol
The protocol used to communicate to web services/documents and resources. The standard defines a protocol and semantics that allow web consumers to communicate with web services.
HTTPS HTTPS defines the use of Transport Layer Security (TLS) as a sublayer under the regular HTTP protocol.
URIs beginning with ‘https’ tell clients to use this encrypted variant of the HTTP protocol rather than unencrypted variant.
JSON JavaScript Object Notation
An open standard textual data format natively understood by JavaScript interpreters.
JSON Schema Used to define JSON documents. JSON Schema documents are written in a JSON Domain-Specific Language.
JWT A JSON Web Token
A security token that is passed in a request that identifies the caller and optionally their capabilities.
Natural Key A natural key is a Resource identifier composed of data that uniquely describes data using the Resource’s own attributes.
OAuth A protocol that allows resource owners to authorise third-party access to their server resources without sharing their credentials. The result of the protocol is a client (often a browser) receiving a JWT.
OpenID Connect An authorisation framework built on top of OAuth 2.0.
Representation A textual or binary rendition of some Resource state. Resource state may have more than one representation. For example, an Image resource might support the following representations: jpeg, png or tiff. When a resource is retrieved the internal (private) state is converted to an acceptable representation. When a Resource is created/updated the supplied representation is converted into the (private) state of the Resource.
Resource An item held on a computer system that is accessible over the internet and is addressed by a URI. Representations of the Resource are exchanged between a client accessing a Resource and a server exposing the Resource.
REST Representational State Transfer.
RESTful Web services Web Services that follow REST principles.
Schematron Schematron is a rule-based validation language for making assertions about the presence or absence of patterns of elements, attributes and values in XML documents.
Surrogate Key A key with no business meaning.
SVG Scaler Vector Graphics
It is a XML-based language for describing vector graphical representations of images or graphics.
TLS/SSL Transport Layer Security / Secure Socket Layer
TLS is the successor to SSL. Both are cryptographic security protocols that provide secure communications and authentication of server and optionally the client.
UUID Universally Unique Identifier
A UUID is a 128-bit number used to identify information in computer systems. When generated according to the standard methods, UUIDs are for practical purposes unique, without depending for their uniqueness on a central registration authority or coordination between the parties generating them.
Web Application A web application or web app is a client–server software application in which the client (or user interface) runs in a web browser as a JavaScript program.
Web Services Network accessible service interface. A web service is a computing service offered to another computing client or service that communicate with each other via the World Wide Web.
X.509 A standard format for public key certificates. X.509 certificates are used by TLS/SSL.
XML eXtensible Markup Language
XML is a mark-up language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable.
XML Schema Specifies how to formally describe the elements in an XML document. XML Schema documents are written in an XML DSL.
YAML Is a human-readable data serialisation language. It is commonly used for configuration files.

Web Service API Principles

When building a Web Service API the following principles should apply:

Use common security protocols

  • Control access to authenticated and authorised clients. Each API should use the same authentication protocol/framework. This is done so that a participant organisation has a single way of proving that they should have access for all their connections to the Lloyd's APIs.
Publish API metadata
  • Provide for discovery and description of service endpoints. This is so the developers that have to program to interface the API have a single place to find specifications, processes and protocols, such that they can create programs that interface successfully with the API endpoint.
Hide information when possible
  • Hiding what you do not need to know, such as internal keys, processing steps, where the server is located, what language was the service written in, how is the data stored, what algorithm is used? – This is so that underlying implementation details are hidden from clients (allowing the underlying details to be changed/upgraded).
  • “When in doubt leave it out” – extraneous details exposed become a dependency between client and service.
Don’t maintain conversation state (stateless)
  • Neither side of an interaction should need to remember that they are having a conversation. This simplifies implementation and operation of web services.
  • Requests should not depend on state maintained from previous interactions. This enables simpler cheaper deployment configurations, saving money on build and ongoing management.
  • APIs will not require clients or services to maintain state about an interaction (beyond that of the ephemeral requests in transit).
Minimise mutability
  • Immutable whenever possible. Information that is read-only and immutable (not subject to change) can be stored in different places without issue and can be cached forever.
  • If you can design a system such that resources do not change, then great simplicity follows.
Provide anonymity to web service implementations
  • The URI of a web service will hide the location, nature and ownership of the actual service implementation.
  • Clients do not need to know this information, and services can be changed to use other options if and when desired.
Common information representation style
  • All services will expose their Information models in a consistent style (XML and/or JSON).
  • Resource references will be consistently structured.
  • Both measures simplify and harmonise participant development tasks.
Entities will be modelled as Resources
  • Resource identities will be modelled using natural business keys wherever possible.
  • Internal non-business keys will not be exposed in the information representation. Exposing such keys is a known anti-pattern, leading to downstream costs and interdependencies.

Standard Synopsis

The following list of characteristics is not normative but summarises the broad shape of this web services standard:

  • Resource based API Design is used throughout as opposed to an operation-based design.
  • A REST style architectural style is used. SOAP is not supported.
  • Message Originated interaction types are not supported.
  • Low level Publish/Subscribe web service interfaces are not supported.
  • Resources are addressed using URIs. Resources are identified using natural business keys.
  • Access to resources is always via HTTPS and is authenticated using OAuth 2.0.
  • Functional operations supported are only: GET, POST, PUT and DELETE.
  • Resources may support different content types including unstructured and semi structured.
  • HTTP content negotiation is used along with optimistic concurrency control via the use of If-Unmodified-Since and If-Match.
  • HTTP cache headers are utilised and must be respected.
  • HTTP response codes are utilised and must be respected.
  • A common error payload structure and a common collection payload structure are used.
  • Structured data Resources are represented in JSON and XML.
  • XML Schema and JSON Schema are used to define valid structured data.
  • Swagger is used to define the Web Service API.
  • Changes to Resource state are mostly modelled as intent Resources.
  • Long running operations are modelled as intent Resources.
  • Resources are organised into collections of Resources of the same type.
  • Resource collections can be filtered using query parameters.
  • Resource collections can be ordered using query parameters.
  • Resource collections can be paged through using query parameters.
  • Resources that have changed or been added can be filtered using query parameters.
  • Resource collections can be filtered and ordered by last modification time.
  • Structured Resource representations in JSON and XML may have the set of fields returned, reduced using query parameters.
  • Links (associations) from one Resource to another are represented by URIs.
  • Linked Resources may be inlined in the Resource representation in some cases, this is controlled using query parameters.
  • The major version of the API being used is controlled by the URI path.
  • Requests are performed over HTTPS channels with mutual certificate authentication.
  • Requests include JSON Web Tokens that identify the principal and can be used for authorisation.

High Level Model

This API standard assumes a single combined API that is made up of several "endpoints". Each endpoint is a nexus of Resources that represent a set of linked business concepts. Each API endpoint may be implemented by a separate backend service. The standard assumes that a façade layer exists that ties these distinct services together into a single Web Service API.

High Level Model Diagram

This standard refers to the roles of consumer and providers as shown on the diagram above.

API Characteristics

The API characteristics details the required behaviour of API consumers and providers when describing, defining, initiating, accessing, processing, and responding with respect to a Web Application Programming Interface (API).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119.

Resource Model

Overall Web Service Model

There are two main ways of presenting web services, the Operation Model and the Resource Model.

The Resource Model focuses on data that can be created, updated, deleted and retrieved. These four fixed operations operate on many Resources. Resources are mostly collections but some singletons MAY exist. When some kind of action needs to be performed then a Resource is defined that represents that action and the parameters of the action become the resource state. To cause the action to happen a new Resource instance is created. Resources are addressed using a URI; each resource in a collection is accessed via a distinct URI. Resource representations MAY contain URIs to other Resources.

The World Wide Web uses the resource model and HTTP directly supports the four Resource operations.

This standard uses the Resource Model. SOAP must not be supported.

Endpoints may include non RESTful components but these should only be included in an Endpoint for compatibility reasons. It is strongly recommended that new interfaces are wholly modelled as Resources.

Resource Meta Model

Resources can in general be either unstructured (images, sounds, free text) or structured data (objects, lists, dictionaries, numbers, dates). Some Resources may be modelled as a combination of structured data and unstructured data. These Resources have more than one part and are called multi-part Resources.

There are several kinds of Resource:

Immutable never change once created
Inert can be changed but does not represent: a process or workflow e.g. a blob file in a blob store or a reference data record
Active can be changed but does not represent: a process or workflow e.g. a blob file in a blob store or a reference data record
Singleton represents a single Resource
Collection represents a list of Resources of the same type

The meta model of a structured Resource is as follows:

Resource Meta Model Diagram

Structured Resources

Resources that represent structured data have Resource state that is modelled as a set of fields that contain values. Each field has a name and is of a specific type. Fields may be singular values or lists of values. Field types MAY be primitive types like number or string. Field types MAY also be structure types.

Structures comprises fields with the same rules as Resources (but without any keys). Inheritance may be supported in the Information Model but each Resource in the Resource model can hold only one fixed overall type.

A Resource collection holds a list of Resources. Each and every Resource in the Resource collection must be a structured data resource or a Multipart Resource.

Where a collection of unstructured Resources is required, a structured Resource collection can be defined that has a field holding a URI of an unstructured Resource.

Unstructured Resources

Unstructured Resources do not have structured representations. Unstructured Resources are only available as unstructured representations, for example a jpg image or a text file.

Endpoint designs may describe Resources that only have unstructured representations.

In most cases there is an accompanying partner Structured Resource that contains as one of its fields a link to the Unstructured Resource.

Multi part Resources

Some resources may be represented as a combination of structured and unstructured data, for example a file and metadata about the file being a single Resource. In this case the multiple types of data may be passed as multipart mime payload structures (in POST, PUT and GET request/responses).

Some operations on a Resource URI may only accept/return the structured or unstructured parts; this behaviour must be specified in the endpoint design. Resources may have alternate view Resource URIs that accept/return only one part of the Resource.

The Appendix - Multipart Resource Example Endpoint Rules contains an example of how these rules might be specified in an endpoint design.

An endpoint design must specify the behaviour for each Resource URI with respect to support for multipart mime and the allowable types of the multiparts. As it is not possible to format an HTTP Accept header in such a way as to specify the types of the parts, the endpoint specification must detail the types returned from a GET operation that returns multipart mime.

Service Meta Resources

Each Endpoint may have independent backend service.

If there are more than one Endpoint version in production, the versions may or may not be routed to the same backend service. Each endpoint can therefore be operationally separate from the other endpoints A mechanism is required to facilitate smooth running that can be used for determining the operational state of the service that implements the API. These meta resources will be used to ensure continued availably in the face of service failure.

Every Endpoint must implement a set of meta resources, the minimum set is as follows:

  1. version
  2. health

These Resources MUST only support the GET method.

The ‘/version’ Resource Implementation first verifies that the client is authenticated and is an authorised client, the endpoint then returns details of the versions of the endpoint specification and the version of the build of the backend service software.

The ‘/health’ Resource implementation will not perform authentication nor authorisation but will perform a self-check and return either a 2XX response code or a 5XX response code. The service should validate its configuration and check that it can access necessary services such as databases, if these checks succeed then the service MUST return a 2XX response code.

Additional meta resources MAY be defined in the Endpoint design if required.

These additional meta Resources might present usage counts or other metadata. Reduced capacity or increased failure rates are not in themselves reasons to return a 5XX from a health implementation. Thresholds should be supported and carefully tested.

Resource Scope

Resource scope defines a boundary; Resources within the boundary maintain referential integrity. Referential integrity here implies that a link from one Resource A to another Resource B cannot be left in an inconsistent state because of Resource B being deleted. Two Resources on either side of the boundary are not required to maintain referential integrity with respect to each other. The definition of the Resource scope[s] must be present in the Endpoint design if there is more than one scope within the Endpoint design. Each Resource defined in an Endpoint design must be allocated to a Resource scope.

Two Resources that are within the same scope must maintain referential integrity between the Resources. Two Resources where one that exists outside the scope and another exists inside the scope should be assumed to have loose association integrity. Loose association integrity allows for links to exist to Resources that don’t exist yet or did exist.

Linked Resources within the same scope may support being expanded, as described in Views; resources from other scopes should not support being be expanded.

Resource scopes should not normally extend beyond a single endpoint design. The default resource scope for an endpoint is a single scope that encompasses all Resources defined by the endpoint design. If an endpoint design does not mention scopes then this default must be assumed.

Interaction Patterns

There are several different possible web service interaction patterns, such as synchronous CRUD, Asynchronous CRUD, Publish/Subscribe, Events.

This version of the standard allows for synchronous interaction between consumer and provider. Events will be modelled as Resource collections without a notification mechanism.

Publish/Subscribe is explicitly out of scope of this standard.

An asynchronous interaction pattern with callback is expected to be added to this standard in a later version, at which point we will address the additional complexities of routing, identity and security with respect to callbacks. This version of the standard does not directly support asynchronous interaction patterns between consumers and providers.

Information Model

The information model is made up of the Logical Model, the Resource Model and Representation specifications.

The Resource model provides a view of the service made up of web Resources that together form the basis of interacting with the service.

The Representation specifications define the allowable interchange formats supported for each Resource (for example a JSON document).

Information Model Diagram

Logical Model

Each Endpoint design must be modelled as a UML class diagram and the model must include all structured Resources within the Endpoint. Each structured Resource must be modelled by a UML class and include all defined fields, structures and associations that will exist in the structured data representations (XML/JSON) of the Resource.

The full UML Class model for an Endpoint is the Logical Model of that Endpoint.

The Information model class names will be used as the Resource type names. Business names must be used in the Information model not project or programme names. For an entity to be mapped to a Resource it should have a business key (natural key). Classes that do not map to Resources must be mapped to Structures (value types). UML classes must not have any operations defined. Fields in UML classes must only have public visibility.

The Endpoint design is not a Low-Level Design for the implementing service. The Endpoint design does not contain implementation details.

The endpoint design must not contain any classes/concepts that are not exposed via the API.

Resource Model

The Resource model describes the set of Resources that the Endpoint defines. The Resource model includes field definitions and structure definitions as required to define the complete Model of each Resource.

Resource state is required to be described in the Endpoint design for that Resource.

The Resource model is then used to create the Representation specifications that include open api specifications that will include payload definitions for the service interactions. Parts of the Resource model will be translated into payload schemas.

Resource Identity

The identity of each Resource is a member of a set of values. The value space of each Resource identity must be defined in the Endpoint specification and detail the allowable set of values. The value space is not expected to be a URI but should be a business recognisable key.

For Resource collections, every Resource within the collection will have a distinct value in the identity value space. The identity value of a Resource is also known as the Resource key.

The Resource identity value space must be defined for each Resource in its Endpoint design.

Each Resource instance can be addressed via one or more URIs. There is always a single canonical URI for each Resource.

The identity of the Resource is normally directly embedded within the canonical URI.

The Resource design must specify a mapping from the identity value space to the canonical URI value space. The Resource design may specify other URI mappings to non-canonical Resources.

The Resource identity should be constructed from one or more fields in the Resource model.

The Resource Identity should be carried within the HTTP response payload within the structured data in a commonly accepted location (in addition to the fields that are used to construct the identity).

The Resource Identity should be carried in the structured response as a pseudo field with the name ‘id’ (lower case) to hold the identity value.

Mapping Logical Model to Resource Model

The Resource model is created from the Logical model. The Resource model comprises Resources and Structures.

The process of creating the Resource Model involves taking each UML Class in the Logical Model and determining if it should be represented as a Resource or as a field structure.

Structures define value types that can be the value of a field.

Mapping Logical Model to Resource Model Diagram

Every part of the Resource model must be derived from a class, its fields and associations that exist in the Logical class model.

Values within a Resource do not have their own independent identity. Resources have an identity and must be identifiable (i.e. they cannot be a pure value), generally only UML Classes with natural business keys should be promoted as Resources.

Business Keys

Resources are generally durable objects that exist for as long as the business requirement need them to exist. To provide this durability, Resources are commonly persisted in a storage service (e.g. SQL DB, Document DB or file in filesystem). Storage services require a key to be able to perform read, write, and delete operations on particular data instances.

As specified in Resource Identity, the identity of a Resource which is embedded in the URI is the mechanism used by a backend service to relate the Resource identity to the Resource persisted state.

A Business Key is a business recognisable value that is used as the Resource identity.

Internal persistence primary keys are not business keys. If there is no appropriate natural business key for a Resource Identity, then a surrogate key should be used (e.g. UUID, Hash).

If a business key exists for a Class in the Information model, then this key MUST be used as the identity of the respective Resource.

If no business key exists for a Class then one of the following MUST be used for the Resource Identity:

  1. A key constructed from attributes of the class, by concatenation.
  2. A key picked from some abstract value space (e.g. UUID).
  3. A key generated from a one-way function using Resource attributes or the whole Resource state as input.

An example of a good one-way function is SHA-256. If internal storage keys were present in the Resource Model, this would leak service implementation detail outside of the service and would comprise a security risk.

Internal storage keys must not be present in the Resource Model. A Resource identity must have a lifetime beyond (and not tied to) the persistence store provider implementation.

Class Relationship

The Logical model MAY contain classes that have associations between them.

There are several types of relationship that can exist between classes in the information model; these are: association, aggregation and composition. When the Information model is converted to the Resource model each of these relationships will be mapped to a Resource field. The Resource field will be either a structure or a link.

Where there is a one-to-many or a many-too-many association between two classes that are both mapped as a Resource, then the association is mapped to a field that is a list of links or a list of business keys or a list that has many pairs of a link and also a business key.

Where multiway (n-ary) associations exist, they are mapped to fields that are lists of a structure that contain links to the other Resources. UML Class associations should be mapped as Resources.

Association Links (Resource Reference)

The Information model includes associations between classes. Associations in the Logical Model are mapped to Resource Fields that should contain a business key and MAY contain a link (or a list of links).

Links are pointers to a web Resource. Links are represented as URIs.

Links are not required to be stored as URIs in backend implementations if an alternative (e.g. the identity) is available.

Fields that hold values that are identities (business keys) of Resources MAY store the Resource URI alongside the identity value.

Utility Links

Resource and Collection Resource document representations MAY contain utility links. Utility links are a mechanism that allow clients to discover additional Resources or Subsets of Resource collections. Utility links are not defined in the Logical model. Utility Links can provide metadata about a Resources where applicable.

Examples of possible utility links:
Utility Link Link Type
Canonical Resource URI canonical
Alternative URI alternate
Next Page next
Previous Page prev

Links are held within a link structure, which can contain one or many links. Utility links are held in a link structure at the root of the document. The link format is derived from the Atom link structure.

Representations

Data sent between web service clients and web service implementations needs to be passed in an agreed format. A web service MAY support more than one representation of the Resource model. HTTP has a mechanism using MIME types, for negotiating the content type that are sent or received for each resource (e.g. XML, JSON, YAML, and SVG). HTTP can carry either textual or binary data in its payload. Each supported content type (representation) requires a mapping to and/or from the Resource model.

For structured Resources the two supported formats are XML and JSON: XML:

  1. Appropriate as backbone/back-office format.
  2. Has strong tool and framework support.
  3. Has expressive schema languages XSD, Schematron.
  4. Has strong connected standards: XPATH, XSLT.
JSON:
  1. Is seen as the most developer friendly.
  2. Is the best representation for UI interfaces.
  3. Is a better match with program data structures (lists and dictionaries).
  4. Now widely adopted by industry players for enterprise APIs e.g. Azure.

When writing XML or JSON schema default values must not be specified.

Web API endpoints should support both JSON and XML data representations. By exception a Resource may only support one of XML or JSON. Resources that represent structured data should support both XML and JSON. Resources that represent structured data must support one of XML or JSON. Where a Resource supports both XML and JSON structured document representations, then the client should send a HTTP accept header with a value of ‘application/json’ or ‘application/xml’. If an Accept header is not specified, servers MAY respond with either format.

GET requests for a Resource either return:

  1. A single structured representation in which case the consumer will receive a XML element/JSON object representing the Resource.
  2. A single unstructured representation in which case the consumer will receive a binary or textual representations of the Resource.
  3. A multiple mime structure containing two or more representations the first of which should be a structured representation in XML or JSON and the subsequent parts in binary or textual representations of the Resource.

GET request for a Resource Collection will return:

  1. A list of Resources (whole or subset of a Resource Collection) in which case the consumer will receive a XML element/JSON object representing the result with fields for next page, previous page, total number of matched resources, etc. and an embedded list containing Resource objects, as referenced in Appendix - Collection Wrapper Document . Any unstructured parts must not be returned.

Implementations may support additional URI patterns with ‘.json’ and ‘.xml’ path suffixes at the end of the path that must be respected if present and allowed by the accept headers, the suffix then determines the content types, these URIs should not be used by machine consumers.

GET requests for unstructured and multi-part Resources will return representations as defined by the endpoint. Resources MAY have alternate view URIs that return either the structured or unstructured part of a Resource. Where a Resource representation uses multipart MIME the first part should be the structured part if one exists.

Events

Streams of events should be modelled as Resource collections. Events are a time series ordered list of Resources. Event Resources will all share a common set of fields but these MAY be extended to include other fields specific to that Resource event type.

Service providers may periodically delete old events Resources. When events are deleted, the deletion must be for all events before a certain creation time. API consumers should not normally be able update/modify Events. API consumers cannot delete individual events. Events will not have a lifecycle state, Events are static, that is, they are not modified after they are processed by clients.

URIs

Opaque URI Vs Pattern URIs

In a pure “Hypermedia As The Engine Of Application State” (HATEOAS) all URIs that are used by clients are created by backend services and passed to clients. Therefore clients never construct URIs and are limited to using the link URIs embedded in the Resource state. The restriction on creating URIs is to enable client discovery of the Resource graph, while not requiring any prior knowledge of the graph.

API consumers should construct their own URIs to published patterns. Understanding of the URI structure is however not required as Resource representations may contain URI links to relevant Resources supporting a pure HATEOAS model.

Endpoint designs must specify which URI patterns are supported for each Resource. The patterns detailed within this specification document must be used without sematic or syntactic change. Additional patterns may be added where additional functionality is required.

Most real world clients are written to consume a specific version of a specific URI. Clients with prior knowledge of the Resource graph and the types of each Resource are allowed to construct their own URIs. Allowing clients to construct URIs allows much greater flexibility to be provided by the Resource model. Examples of this increased flexibility are: control over which Resources are returned from Resource collection, control over what field data is returned, control over which linked Resources are expanded, control over the order of Resources returned from a Resource collection.

URI Structure

The Web Service API has a common URI structure for all Resources.

The names used in the URI must be carefully chosen. The guiding principle is that the domain and path do not contain project names, code names or company named but instead include only business concepts. The path may contain company names where the company is a standards organisation or the market participants would recognise the name as a business entity, examples of appropriate company names might include: ISO, Lloyds, and FCA.

Web Service URI Endpoints must use the shared domain name: api.londonmarketgroup.co.uk

URI Type URI Form
Version meta resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/version
Health meta resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/health
Singleton resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{singletonResource}
Complete collection Resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}
A Resource in a collection https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}/{ResourceID}
View collection resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}/{viewName} or https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{viewName}
A resource in a view collection resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}/{viewName}/{ResourceID} or https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{viewName}/{ResourceID}
A Sub Resource https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}/{ResourceID}/{partName}

The complete collection (i.e. with all defined member Resources) is presented at the path ‘https://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}’. Additional particular views of a collection can be defined.

A view may have its own reduced set of fields, expanded fields, and sort order. The members of the view may be a subset or a superset of the collection. The URI path hierarchy may used to indicate the view.

For example: hhttps://api.londonmarketgroup.co.uk/{Deployment}/{ApiOwnerOrg}/{APIName}/{versionNo}/{collectionResource}/{viewName}[?_expand={*association}&_select={*fieldname}&_order={*fields}&filter={*matchcriteria}

The URI path hierarchy must not be used for expressing relationships between classes. (I.e. no URIs with a path like: ‘market/carrier/0434/offers/44233234’)

The URI path hierarchy may be used for exposing sub Resources that represent a part of a Resource, with a path like: ‘market/carrier/0434/offers/44233234/status’. As described in more detail in Resource Update.

The URI path hierarchy must not contain action words or verbs, for example “createOrder”, “deleteOrder”, “process”, ”handle”, ”manage”, ”perform”, ”apply”, etc.

The API should not contain any project or programme name as a segment of the URI path, only business concepts should be used.

When a URI is created by a client the characters in the URI must be encoded as specified in Appendix - Identity.

Provider implementations must decode encoded characters in URIs so that the distinction between encoded characters and unencoded characters with special meaning is not lost.

Canonical URIs and Resource Ids

Every resource has an identity value and a canonical URI. These two values are returned by default in the structured data representations.

When XML content type is being used, the document root element will include an attribute for the identity and a separate attribute to hold the canonical URI. The attribute and element that hold these values are defined in Appendix - Identity

When JSON content type is being used, the Resource object will include a member for the identity and a separate member for the canonical URI. The members that hold these values are defined in Appendix - Identity.

The identity and canonical URI must be populated in the structured data response to a HTTP-GET on a Resource. The canonical URI should not be populated in the payload of a HTTP-PUT or HTTP-POST. If the canonical URI is present it must be correct. The Resource design must specify in which situations the identity needs be populated for HTTP-PUT and HTTP-POST operations.

For Resource representations in XML and JSON that are returned from a GET request, there must be an entry in the link structure with a relation name of “canonical” with a the value being the canonical URI for that resource.

Interface Semantics

Additional nonstandard query parameters (not matching patterns specified in this document) or URI formats should not be included in Endpoint designs. Where other query parameters or URI formats are defined in an Endpoint design, they must be clearly defined and labelled as being exceptions.

HTTP

Mechanics and Protocol

When using HTTP as a transport there are many options and usages that may lead to inconsistent operating behaviour. This standard specifies a rules to avoid possible inconsistent behaviour.

The following usage of HTTP must be observed:

  1. HTTP 1.0 is not supported.
  2. GET requests must not modify the state of a Resource.
  3. GET requests must not create a Resource. They must be idempotent.
  4. POST requests should create a new Resource if they do not terminate in an error and the resource does not already exist.
  5. PUT requests must update the state of an existing Resource or create a new resource. The PUT requests must be idempotent. The URI must be a valid URI of the specific Resource.
  6. PATCH is not supported.
  7. HEAD must be supported for Resources (not mandatory for Resource Collections).
  8. OPTIONS may be supported.
  9. TRACE may be supported.
  10. State should not be passed to a Resource in URI parameters.

Endpoint designs must specify either PUT or POST to be used when creating a Resource. If the consumer can create the target URI then PUT should be used. If the consumer cannot create a target URI then POST must be used. If a PUT is used to create a Resource the same URI must be usable to update the same Resource.

POST operations on sub Resources must not be supported.

PUT and POST operations should return a representation of the Resource as a response. The representation must be the current state of the Resource (which may be different from that sent in the POST).

Endpoint Resource interactions are expected to follow the rules above in all routine cases. Examples of corner cases might include: standard protocols being reused by the API, adopting pre-existing APIs, non REST interaction, user friendly URIs for testing, and critical performance requirements. Endpoint designs may specify that some interactions break these rules, such situations must be explicitly documented as exceptions. Where a rule breaking interface is provided an alternative Resource representation must be additionally included in the Endpoint (or another Endpoint) that supports the functionality using the recommended approach.

General Rules for HTTP headers

Request headers:

Request Headers Rules
Range headers Are not supported for structured Resources
Cookie Should not be sent by client Must be ignored by service
If-Match Should be included for PUT request
Origin Should not be sent by client

Response headers:

Response Headers Rules
ETag, Last-Modified Should be included
Location May be returned with 3XX response code
Cookie Must not be returned by a Service
Retry-After May be returned with a 503 (service unavailable) response code to indicate the expected service maintenance period May be returned with a 429 (Too Many Requests) response, this indicates how long to wait before making a new request

Message Routing

HTTP allows services to indicate to a consuming client that a Resource has moved. The movement may be temporary or permanent. The Resource movement is indicated by HTTP response codes. There are several functional and operational scenarios that can usefully exploit Resource movement to solve general problems.

Web Service API consumer behavioural requirements:

  1. API clients must correctly react to 307, 308
  2. API client may correctly react to 301, 302 (these codes will not be sent by compliant providers)
  3. Clients may forget the permanent redirect
  4. Clients should remember a permanent redirect for the lifetime of the program instance

Web Service API provider behavioural requirements:

Depending on the Resource model used, it might be possible to resolve a Resource via several URIs. One of these URIs will be the canonical Resource URI. When accessing the Resource via the non-canonical URI, a 301 or 308 should not be returned. When accessing the Resource via the canonical URI a 301 or 308 must not be returned.

Resource Retrieval

Resources may be retrieved/read by API clients, but only if the GET operation is specified in the Endpoint specification for the Resource model.

Most Resource models will support GET operations. Some Resource models do not support GET as they do not maintain any persistent state after Resource creation.

Resource Creation

Resources may be created by API clients, but only if one or both of POST or PUT operations are specified in the Endpoint specification for the Resource model. The payload of the POST or PUT must include a structured resource represented as either JSON or XML (the payload may contain other content in a multipart MIME structure). The Resource state should be returned in the HTTP response. Where a POST method is used, and a persistent Resource is created the response must include the URI of the Resource.

Resource Deletion

Resources may be deleted by API clients, but only if the DELETE operation is specified in the Endpoint specification for the Resource model. If a Resource is deleted and the HTTP operation is successful then a subsequent GET operation should return a 4XX response code.

Resource Update

Resources may be updated by API clients, but only if the PUT operation is specified in the Endpoint specification for the Resource model. To update an existent Resource an HTTP PUT request is made by an API consumer using a Resource URI. The whole Resource state must be updated. The document sent in the PUT replaces the whole state represented by the Resource in the provider. Endpoints specifications may choose to map the logical information model into more than one Resource model. Endpoints specifications may choose to provide sub Resources that represent a part of the Information model. PUT operations on a sub Resource will update the parts of the logical model that the sub Resource maps to. A GET on the parent Resource must then contain the updated field values.

To delete/remove a value of a field in a Resource that field in XML will be absent or or JSON either absent or have a value of null.

Some fields in a Resource may be read-only (e.g. creation date). If clients are not allowed to send values for read-only fields (even if they match the original value) then the endpoint specification must specify the permitted values that can be send in a PUT request.

Synchronisers & Accessors

It is possible for two API consumers to attempt update a resource simultaneously. One of the consumers will win and overwrite the changes of the other without either consumer being aware of the situation.

There are two ways to manage concurrent updates on resources:

  • Pessimistic concurrency control – The service get a lock on the resource. While the resource is locked, no other client can modify it.
  • Optimistic concurrency control – When updates are made to a Resource the PUT request includes a revision code, if the revision code no longer matches the current code then the request fails.

Resources defined under this specification must use optimistic concurrency control via the use of If-Unmodified-Since and If-Match HTTP headers along with last modified or etag values to ensure that the Resource has not been modified between reading and writing.

A Resource design may mandate one of these two headers be present in a PUT request and if they are not present, then a 403 response code should be returned by the provider.

Applications should be written such that wherever possible such clashes are automatically retried after retrieving the latest Resource state. End users should only be made aware of such clashes if human remediation is required.

Caching

Caching can be used to increase performance and increase resiliency. Caching can be performed in the Consumer, in a proxy (such as API gateway), or in the providing service.

Data returned from a GET request to an endpoint are either specific to the fine grained privileges of the client identity or they are generally accessible to any authorised client of the service. Services can and should return different caching response headers for these two cases.

Long lived reference data the expected rate of change of reference data is very low but the rate of usage can be high. In this case we do not want to incur the cost of revalidating cache freshness every time the reference data values are used. So in this case the cost of checking the e-tag would be excessive and a max-age would be a more appropriate choice with a value between 3600 and 85,000 seconds.

The choice of max-age or etag depends on the relative frequency of requests vs the cost and size of the response. API providers should set meaningful and reasonable cache response headers. API providers must handle HEAD requests for Resources.

API Providers MAY set cache response headers to: Cache-Control: no-cache

If no-cache is specified then the rules below do not apply.

Responses that are specific to the fine grained privileges of the client identity must have cache response headers set to: Cache-Control: must-revalidate, private

Responses that are generally accessible to authorised clients must have cache response headers set to: Cache-Control: must-revalidate, public

Either a max-age or an etag must be specified. API clients and Intermediaries must only cache content only where the cache response header allows it.

Response Codes

HTTP defines a set of response codes that can be returned from HTTP requests.

For each code we need to specify:

  1. When an API provider is allowed to return the code
  2. What an API consumer must do when it receives the code

The rules for each HTTP operation and the response code returned are detailed in Appendix – Response Code Rules.

Resource Mime Types

HTTP uses MIME types to determine the content type of the payload data. Unstructured representation should use the most appropriate MIME type, the chosen MIME type should be handled appropriately by API consumers.

Structured representations must use one of the following MIME types:

  1. application/xml
  2. application/json

Endpoint design must specify the list of content types that an implementation is allowed to support. If certain content types are mandatory then the Endpoint design must specify this.

Error Handling

Errors can occur when API provider processes a HTTP operation. There are many causes of errors including:

Error Case Response Code Returned
The request URI does not map to a known resource Service must return a 4XX error code
The request URI contains invalid parameters Service must return a 4XX error code
The request payload contains invalid data that fails schema validation Service must return a 4XX error code
The request payload contains data that is incompatible with application invariants Service must return a 4XX error code
The request payload contains data that is incompatible with application state Service must return a 4XX error code
The combination of request payload data and application state exposes an application bug Service should return a 5XX response code but may return a 4XX response code
The backend service depends on a failed component that means the request cannot be processed completely Service must return a 5XX response code
The backend service is unavailable and not responding API gateway function must return a 5XX response code

An error document including an error message should be sent back along with the response code. The error document should machine readable but contain a human readable error message.

The error documents for XML and JSON are defined in Appendix – Error Documents and should be returned from any GET, PUT or POST operation that results in a 4XX or a 5XX response code. The error document should contain helpful information for the client that might help with triaging the error.

The information retuned must not expose internal implementation details (for example stack traces). The information returned may contain correlation identifiers or transaction identifiers that should identify log messages within the service implementation. The document must contain personal information.

The document may contain data values that are directly related to the error. The document should not contain the whole request payload. Services are required to log details of every request that result in a 4XX response code.

The Lloyd’s Web Service Application Programming Interfaces (APIs) is for service to service interaction and not for browser to service. So for example a UI will not make direct calls on the API from the browser. The error messages returned are not for end user consumption.

The error message returned are intended to facilitate operations and development in triaging and debugging issues. The information returned must not conflict with penetration testing stipulations.

There are two broad error cases:

  1. Client induced errors (4XX response codes) Error information should indicate the issue with the client request that is causing the issue, but only in terms of state sent in the request or the URI.
  2. Service failures (5XX response codes) Transaction or correlation identifiers should be returned. Returned Identifiers may be complex structures that contain codes or symbols that indicate the source of the issue. This information is for human consumption and should not be evaluated or acted upon automatically by recipient systems.

Collections

Singletons and Collections

Resources come as singleton Resources or as collections of Resources. The collection is itself a Resource and each item in that collection is also a Resource.

An example of a singleton resource: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders/x743r3s

An example of a collection resource: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders

An example of a view of a collection resource: https://api.londonmarketgroup.co.uk/placement/quotation/v1/openOrders

An example of an individual Resource in a collection: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders/x83af91jp6

All Resources are independently addressable and must not require the more than one class key to be placed in the URI.

Ordering

When a GET is performed on a collocation Resource (and no ordering is specified) the order of Resources in the response is undefined but must be constant.

Order consistency is defined as:

Repeated requests using the same URI must return the same set of Resources in the same order while the whole collection state has not changed. Each Resource must appear only once in each page of results between requests while the whole collection state has not changed.

It is not permitted for the order of Resources returned in a GET changing without any Resource state having changed.

When performing a GET on a collection Resource the set of resources returned can be optionally ordered before being returned.

The order of Resources returned from a GET can be changed by specifying a “_order” parameter. The value of the parameter is a list of field names, e.g. “_order=quoteID,created”. The default order is ascending, if descending order is required for a field then it will be decorated by hyphen e.g. “_order=-created”. The field first in the list has highest precedence when ordering the Resources returned. The fields of the following types may be sorted: numbers, strings, URIs, dates, times, datetimes and enumerations.

Type Order
Number ordinal
String alphabetical
Date, Time, DateTime chronological
URI alphabetical
Enumerations alphabetical

The exact alphabetical ordering provided is implementation dependent and must be specified in the Endpoint design. Implementations must implement a consistent ordering for each field. Differences in ordering that could arise because of different backend implementations of the same endpoint design are not allowed. The endpoint design SHOULD specify the collating sequence that is used for sorting each sortable string field.

Endpoint designs should provide ordering on fields where sensible. Production implementations must support the ordering feature where it is explicitly specified in the endpoint design. Test implementations may omit the ordering functionality but must return a 501 error response code if the request URI contains an unsupported ordering. Resource must not provide an equivalent feature using different syntax or semantics. If the ordering feature is not supported then a response code of 501 must be returned and an error payload must indicate that the ordering feature is not supported. Use of the _order parameter when not supported by the endpoint specification must result in a 4XX response code.

Select Fields

When performing a GET on a Resource the set of fields in the Resource representation can be condensed to a reduced set of fields before being returned.

The set of fields returned from a GET request may be reduced by specifying a “_select” parameter in the URI. The value of the _select parameter is a list of top-level field names separated by commas: e.g. _select=address,quoteID,provisions,created,sourceID

Where a field selection parameter is present in a GET request the return document must only include the fields listed in the field list. Fields defined in the Resource that are not included in the _select field list must not be present in the response document.

A GET response might not include fields that are mandatory in the document schema when a field selection parameter is present, this would cause the document to fail schema validation.

Endpoint Consumers, Providers and Intermediaries must not validate GET responses where a _select query parameter is present using the standard Resource schema. Endpoint designs may specify additional XML and JSON schemas (variant schemas) that may be used to validate responses from such requests.

When performing a GET on the unmodified canonical URI of a Resource, the provider must return the complete information set of the Resource including all fields that have a value.

Optional fields that do not have a value should not be present in the response document (even when specified in the _select parameter).

Resources may also be accessible via non canonical URIs (usually within a collection Resource view) that can expose a subset of fields. The same rules apply for these views that return a subset of the possible fields. The Endpoint design must detail which schema (or none) may be used to validate

Representations when using the field culling feature. Resource must not provide an equivalent feature using different syntax or semantics.

If the field culling feature is specified in the endpoint design but is not supported by the implementation then a response code of 501 must be returned and an error payload must indicate that the field culling feature is not supported by that environment. If a Resource does not support this feature that fact must be stated in the Endpoint design. Use of the _select parameter when not supported by the endpoint specification must result in a 4XX response code.

The list of fields that may be specified in the _select parameter must be stated in the Endpoint design.

The ‘id’ pseudo field should always been returned for each Resource returned, irrespective if it has been specified in the _select list.

Paging

Resource collections can contain arbitrarily large numbers of Resources. An unadorned GET request on a collection conceptually returns the entire set of Resources. In many real world scenarios it is impractical to return the entire Resource set. Implementations may restrict the number of Resources that are returned and provide mechanisms for paging through the entire results set by making several GET requests each one returning a subset of the whole collection.

All GET requests on a Resource collection must return a document that wraps the individual Resource representations. This collection envelope (6.2) includes an attribute that specifies the total number of Resource that can be accessed given the filter query parameters in the URI.

Endpoint designs must specify if paging is supported for each collection Resource defined in the endpoint. If paging is not supported implementations must guarantee that all Resources can be returned in a single GET response. The only practical way of achieving this guarantee is to limit the number of Resources and limit the individual Resource complexity.

If paging is supported for a collection Resources then the following standard URI parameter must be supported by Resource collections:

  1. _pageSize – how many Resources must be returned by the request.
  2. _pageNum – the number of page of results that will be returned.

The largest value of _pageSize that may be specified in a URI is 200, implementations may have their own default value. The actual page size must be included in the result envelope.

The collection envelope also includes a link structure with metadata links for first, last, previous and next pages.

Implementations may return more than 200 Resource in a request, up to an implementation defined maximum, but only if _pageSize has not been specified in the GET request URI. Page number has a value range from 1 upwards.

Views

Endpoint designs may include virtual resource collections that can be:

  1. Resource subset of another collection (omitting Fields).
  2. Field subset of another collection (omitting Resources).
  3. An amalgam of linked Resources (joining associated Resources).
  4. Resource superset of another collection (including fields that are excluded in the standard view).
  5. An enhanced field list collection (including Resources that are not present in the standard view).

These view resource collections are generally read-only but may support POST and PUT operations. Views may provide a historic data view, i.e. increase the set of Resources in the collection beyond that for the primary collection view.

Collection Filtering

The set of Resources returned when performing a GET on a Resource Collection can be reduced from the complete set by adding query parameters to the URI.

The filtering function is made up of one or more criteria that are logically formed together to form the complete filter function.

The GET request will only respond with Resources that match the complete filter function.

Each filter criteria is specified as an individual query parameter appended to the URI. The name of the query parameter is the Resource field name and the value of the parameter can be one of several filter expressions depending on the type of the field.

Only a single query parameter is allowed to be specified for a particular field. For example: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders?status=open

A filter expression may be negated for a field by the presence of a ‘!’ at the beginning of the filter value. Only a single ‘!’ can be present and it must be immediately after the ‘=’. For example: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders?status=!closed,revoked [No resources would be returned with a status of closed or revoked.]

The fields of the following types MAY be filtered on: numbers, strings, URIs, dates, times, datetimes, enumerations. URIs and enumerations are treated as strings.

When filters use the ‘..’ and ‘…’ then the matches are always inclusive. For example: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders?numFollowers = 2..4 [Only orders that nave numFollowers with values of 2,3, or 4 will be matched]

When the field is a structure type (i.e. not a simple type) then the field name must not be used on its own in a query parameter. Where a field is of structure type (or list of structure) then sub fields within the structure may be referenced in a query filter but only if specifically allowed by the Endpoint design. Sub fields within a structure are specified using the ‘.’ Notation to separate the top level field names from the lower level structure field name. For example: https://api.londonmarketgroup.co.uk/placement/quotation/v1/orders?status=address.postcode=94043

The API endpoint providers must only return Resources from the Resource collection in question that match all of the criteria query parameters (i.e. the terms are logically formed together).

Endpoint designs must not provide an equivalent feature using different syntax or semantics.

The allowable criteria for each Resource Collection must be specified in the Endpoint design for each supported view. Collections may have an empty set of criteria specified, in which case filters must not be specified in the URI for that collection.

Production Endpoint implementations must support the filtering criteria that have been defined. Other test environments must not implement Endpoints with reduced filtering functionality (e.g. a mocked test service).

If the filtering criteria specified in an Endpoint design are not supported by an implementation, then a response code of 501 must be returned and an error payload must indicate that the filtering feature is not supported.

Use of the filter parameter when not supported by the endpoint specification must result in a 4XX response code.

Date Fields

Field values of type Date may be specified by the endpoint design to support filtering. If the endpoint design does not explicitly state that a filtering option is supported on a date field then providers are not required to implement the feature and clients should not expect the feature to be implemented.

The table below summarises the supported standard filtering for date fields:

Filter Type Format Examples
Single Value fieldname=adate Foo=2019-08-21
Multiple Values fieldname=adate,bdate,cdate Foo=2019-08-28,2019-09-21,2019-11-21
A range of values fieldname=range(adate,incl,bdate,excl) Foo=range(2019-08-01,incl,2019-08-31,incl) Foo=range(2019-07-30,excl,2019-09-01, excl) Foo=!range(2019-08-01,incl,2019-08-31,incl)
fieldname=adate..bdate Foo=2019-08-01..2019-08-31
fieldname=...adate Foo=...2019-08-31
fieldname=adate… Foo=2019-08-31
Fractional days are not supported.

Datetime Fields

Field values of type Datetime may be specified by the endpoint design to support filtering. If the endpoint design does not explicitly state that a filtering option is supported on a datetime field then providers are not required to implement the feature and clients should not expect the feature to be implemented.

Fractional seconds may be supported in the field values and if they are this support must be specified in the Endpoint design. If fractional second are supported for a field then fractional seconds must be supported in the filter values for that field. If fractional second are not supported for a field then fractional seconds must not be supported in the filter values for that field and a 4XX error code must be returned if they are present.

The value must be a valid ISO8601 date time value (with optional timezone, which will be normalized away to UTC if present).

The table below summarises the supported standard filtering for datetime fields:

Filter Type Format Examples
Single Value fieldname=adate Foo=2019-08-21T15:29:24
Multiple Values fieldname=adate,bdate,cdate Foo=2019-08-28T15:29:24,2019-09-21T09:59:54, 2019-11-21T15:29:24
A range of values fieldname=range(adate,incl,bdate,excl) Foo=range(2019-08-01T15:29:24,incl, 2019-08-31T15:29:24,incl) Foo=range(2019-08-01T15:29:24,incl, 2019-08-31T15:29:24,incl) Foo=range(2019-08-01T15:29:24,incl, 2019-08-31T15:29:24,incl)
fieldname=adate..bdate Foo=2019-08-01T15:29:24..2019-08-31T15:29:24
fieldname=...adate Foo=...2019-08-31T15:29:24
fieldname=adate… Foo=...2019-08-31T15:29:24

Number Fields

Field values of type number may be specified by the endpoint design to support filtering. If the endpoint design does not explicitly state that a filtering option is supported on a number field then providers are not required to implement the feature and clients should not expect the feature to be implemented.

Numbers are either integer or floating point and may or may not be signed. The endpoint specification will detail the supported value space for a numeric field.

The table below summarises the supported standard filtering for number fields:

Filter Type Format Examples
Single Value fieldname=anumber Foo=2019
Multiple Values fieldname=anumber,bnumber,cnumber Foo=2019,2020,2021
A range of values fieldname=range(anumber,incl,bnumber,incl) fieldname=range(anumber,incl,bnumber,excl) fieldname=range(anumber,excl,bnumber,incl) fieldname=range(anumber,excl,bnumber,excl) Foo=range(2019,incl,2018,incl) Foo=range(2011,excl,2019,excl) Foo=!range(2012,incl,2018,incl)
fieldname=anumber..bnumber Foo=2017..2019
fieldname=...anumber Foo=...2019
fieldname=anumber… Foo=2019..

String Fields

Field values of type string may be specified by the endpoint design to support filtering. If the endpoint design does not explicitly state that a filtering option is supported on a string field then providers are not required to implement the feature and clients should not expect the feature to be implemented.

The endpoint specification will detail the supported value space for a string field.

The table below summarises the supported standard filtering for string fields:

Filter Type Format Examples
Whole Single value (exact match, whole string, case sensitive) fieldname=astring fieldname=match_casesens(astring) Foo=A7 Foo=match_casesens(A7)
Whole Multiple values (exact match, whole string, case sensitive) fieldname=astring,bstring,cstring fieldname=match_casesens(astring,bstring,cstring) Foo=A7,B3,Q3 Foo=match_casesens(A7,B3,Q3)
Contains text match case sensitive fieldname=contains_casesens(astring) fieldname=contains_casesens(astring,bstring,cstring) Foo=contains_casesens(B)
Prefix text match case sensitive fieldname=prefix_casesens(astring) fieldname= prefix _casesens(astring,bstring,cstring) Foo=prefix_casesens(B)
Suffix text match case sensitive fieldname=suffix_casesens(astring) fieldname=suffix_casesens(astring,bstring,cstring) Foo=suffix_casesens(B)
Whole text match case insensitive (exact match, whole string, case sensitive) fieldname=match(astring) fieldname=match(astring,bstring,cstring) Foo=match(A,B)
Contains text match case insensitive fieldname=contains(astring) fieldname=contains(astring,bstring,cstring) Foo=contains(A,B)
Prefix text match case insensitive fieldname=prefix(astring) fieldname=prefix(astring,bstring,cstring) Foo=prefix(A,B)
Suffix text match case insensitive fieldname=suffix(astring) fieldname=suffix(astring,bstring,cstring) Foo=suffix(A,B)

Each text match function takes one or more values, if any of the values matches the content of the string (according to the function’s semantics) then the filter is a match for that Resource instance.

The ‘contains’ and ‘contains_casesens’ functions look for at least one instance of one of the parameter values in the specified field.

The ‘match’ and ‘match_casesens’ functions ensure the whole string matches character by character.

The ‘prefix’ and ‘prefix_casesens’ functions ensure the beginning of the string matches.

The ‘suffix’ and ‘suffix_casesens’ functions ensure the end of the string matches.

The table above defines the allowed text match functions for this version of the specification. Endpoints may specify additional string matching functions.

If implementations cannot correctly implement either exact matching or case insensitive matching then the implementation must return a 501 error code.

Endpoint implementations that support filtering on string fields should support as a minimum the following functions: ‘match_casesens’, ‘contains’, ‘prefix’ and ‘suffix’. Where ‘match_casesens’ is supported then the unadorned equivalent must be supported, i.e both “Foo=A7,B3,Q3” and “Foo=match_casesens(A7,B3,Q3)” will be supported.

Repeating Fields

Where filters are supported for a field that can have multiple values then the semantics are that any one of the multiple value matching the filter expression is sufficient for that filter to be true for that Resource instance.

Where both the filter and the field have multiple values then any match of any field value against any function value will cause the filter to be match for that Resource instance.

Expanding Linked Resources

When performing a GET on a Resource, the links to Resources can be on request be expanded inline into additional structure fields containing the actual remote Resource representation.

Where a Resource A has a field that contains a link to another Resource B of a different type that exists within the same scope, then the linked Resource B may be expanded and inlined within the response for the Resource A. The expansion must not happen by default and must only happen when explicitly requested.

Expanding can only be supported amongst Resources defined within the same Endpoint design. Expanding must only be supported for links that are explicitly affirmed in the Endpoint design.

The set of fields that can be expanded in the response from a GET request are be stated by specifying a “_expand” parameter in the URI. The value of the _expand parameter is a list of field names separated by a comma. The fields specified must contain a link or a Resource identity. For example _expand=authority,agent,carrier

Endpoint Consumers, Providers and Intermediaries must not validate GET responses where a _expand query parameter is present using the standard Resource schema. Endpoint designs MAY specify additional XML and JSON schemas (variant schemas) that MAY be used to validate responses from such requests.

Field culling may be permitted by the Endpoint design on fields within the expanded Resource. If field culling is not present then the full Resource field set must be present in the inlined field.

Endpoint designs may specify additional XML and JSON schemas (variant schemas) that include the external Resource fields within the reference field.

When reusing existing XML schemas it might not be possible to support Resource reference expanding due to the structure of the schema.

Production implementations must support the field expanding feature if it is specified in the Endpoint design. Implementations must not provide an equivalent feature using different syntax or semantics. If the field expanding feature is not supported in test implementations and it is requested in the URI, then a response code of 501 must be returned and an error payload must indicate that the field expanding feature is not implemented.

Use of the _expand parameter when not supported by the endpoint specification or containing an unsupported field name must result in a 4XX response code.

Last Modified

The Endpoints must consistently implement tracking of modifications to Resources and Resource collections.

Last-modified HTTP response header

When any single Resource is retrieved using a GET or HEAD method then the latest modification (or creation datetime) for that resource must be returned in the HTTP response header “last-modified”.

The value must be a valid RFC 1123 date time value.

When any Resource Collection is retrieved using a GET or HEAD method then the HTTP response header “last-modified” must be present in the response.

Endpoints must explicitly state for a Resource collection that last-modified will not be retuned (i.e. this is a default feature).

The value of the “last-modified” response header returned for a Resource Collection must be the most recent last modified value over all the Resources in the collection that match the filter expression (or all Resources if no filters are present in the URI).

The “last-modified” value is calculated by taking the most recent modification value over all the Resources and the value is not the last time a Resource was added or removed from a collection.

The page size does not affect the value of the “last-modified” response header as it is calculated over all matching Resources in the collection and not just those returned in that page.

If the collection is empty the “last-modified” response header may be omitted in the response. If the collection is empty and a “last-modified” response header IT returned the header value must be the datetime when the resource collection was emptied.

Last Modified Order

Where specified in an Endpoint design the pseudo field “_last_modified” may be included as the value for the _order query perimeter.

Order Meaning
_order=_last_modified The most recently changed/created Resources in a collection will come last in the returned set of Resources. I.e. ascending order of last modification datetime. Where all match Resources exceed the maximum page size then higher page numbers will contain increasingly newly modified Resources.
_order=-_last_modified The least recently changed/created Resources in a collection will come last in the returned set of Resources. I.e. descending order of last modification datetime. Where all match Resources exceed the maximum page size then higher page numbers will contain decreasingly newly modified Resources.

Last Modified Filters

Where explicitly specified in an Endpoint design the pseudo field “_last_modified” may be included as a query perimeter. The value must be a valid ISO8601 date time value (with optional timezone, which will be normalized away to UTC if present).

Any valid datetime filter specified in div 5.6.2 may be specified. For example: _last_modified=range(2019-08-01T15:29:24,incl,2019-08-31T15:29:24,incl) _last_modified=range(2019-07-30T15:29:24,excl,2019-09-01T15:29:24,excl) _last_modified=!range(2019-08-01T15:29:24,incl,2019-08-31T15:29:24,incl) _last_modified=2019-08-01T15:29:24..2019-08-31T15:29:24 _last_modified=...2019-08-31T15:29:24 _last_modified=2019-08-31T15:29:24…

Retrieving new or updated Resources from a Collection

Clients may use a combination of _last_modified= and _order=_last_modified along with the value returned in the last-modified http response header to retrieve the Resources in a collection that have been added or changed.

Generally clients will need to maintain a datetime high water datetime state value (or derive such a value) to efficiently retrieve only the new or changed Resources. This allows for RESTFull sessionless provider implementations.

Document Types

Schemas

HTTP interactions GET, PUT and POST involve data being sent between the API consumer and the API provider. For structured Resources, this data will be sent in a XML and/or JSON document representation.

The allowable value set of structured documents that can be sent or received from a Resource needs to be specified in Schema documents in the API design specification.

Endpoint designs must provide XML Schema for all Resources that support an XML representation. The Endpoint designs may provide a Schematron schema .

XML Schemas will follow the pattern Garden of Eden pattern. The XML Schemas will be open to extension by attribute and element. The form of the XML will be restricted to a structure that can be cleanly bi-directionally converted to JSON. Repeated elements (max occurs > 1) may only exist in isolation within a parent element (i.e wrapped in a container element).

JSON Schema will be created to specify the JSON representations. API Consumers must send schema valid content to API Providers. API Providers must send schema valid content to API Consumers.

API Providers may validate received content against published schemas. API Consumers may validate received content against published schemas. Content that fails validation must be rejected and lead to error processing.

As XML is more expressive than JSON, a common approach is to first define the JSON schema and then define the XML schema ensuring the value space is equivalent.

Collection Resources have a common XML and JSON structure that is shared by all collection Resources. The Endpoint design must include a document schema definition for each collection Resource that must follow this common structure. The common structure is defined in appendix 6.2.

Document Handling

Structured Resources are modelled as documents that can be retrieved and may be able to be created/updated (POST/PUT). Certain processing steps need to be performed by the consumer and the provider of a Resource during these operations:

When a document is generated, it should be validated against its schema (except where schema validation is expressly disallowed by this specification).

When a document is received, it should be validated against its schema (except where schema validation is expressly disallowed by this specification).

When a document is received, any externalised reference data fields should be validated as being a member of the respective reference data set.

When an unexpected content type is received by a client from a service, the details must be logged by the client and processing must be terminated. If the unexpected content is received in a POST or a PUT request, then a 501 response code must be returned.

Resources may be representational or integral. Representational Resources are stored in a private internal structure that is different from that passed over the http connection. Integral Resources are stored as their representation, byte for byte. There is often information loss when converting between a representation and the private internal store. Resources that have representations that are hashed or signed before creation must be integral Resources.

The rules below allow Representational Resources implementations to discard specific classes of information that might exist in the representation received.

The Endpoint design must specify for each Resource if it is representational or integral.

For integral Resources the representation supplied in the original POST or subsequent PUT must be returned byte for byte identical when a GET is performed on the canonical URI and the response representation is the same as was used in the original POST/PUT.

For representational Resources when a document is received in a POST or PUT request the document is converted to the internal object implementation. For structured Resources (JSON/XML) the following information may be discarded:

  1. Whitespace
  2. Comments
  3. Arrangement of Namespace definitions
  4. Unrecognised XML attributes
  5. Unrecognised XML elements
  6. Unrecognised JSON keys (and the values that go with them)
  7. Order of values in unordered lists (as defined in the logical Information model)
  8. The access URI of a linked Resource

Unrecognised XML elements, XML attributes and JSON key/value pairs are defined here as those artefacts that are not specifically listed as expected to be present (mandatory or optionally) within a Resource or within a structure used in a Resource. The fact that an artefact is defined within a schema does not make it recognised, it must be specifically referenced by name in the XML element or the JSON object.

When a representational Resource is retrieved with a GET any and all of the above information may be missing when compared with the document sent in a POST or PUT.

The above rule does not imply that namespaces are optional. All XML elements must be in the correct namespace for the document to validate against its schema. Where the document schemas allow unspecified content to be in the document (via element or attribute wildcards) the receiver MAY discard this content and must not treat this as unexpected content and must not terminate processing.

Standard Value Types

Resource representations can contain a variety of formats for primitive types. A good example is date, there are many well accepted date formats many of these are mutually incompatible or inconsistent.

The following table describes the standard formats for primitive data.

Endpoint Design should use these formats when defining the physical document schemas:

Data Agreed Format Comments
Date ISO 8601 / XSD:date e.g. “2008-10-31”
Time ISO 8601 / XSD:time e.g. “15:07:38.6875000-05:00”
DateTime ISO 8601 / XSD:date e.g. “2008-10-31T15:07:38.6875000-05:00”
UUID ITU-T Rec. X.667 | ISO/IEC 9834-8
Country Code ISO 3166-1 alpha-3 – three-letter country codes
Currency Code ISO 4217 Non-standard codes are accepted (Lloyd’s extensions)

Machine Readable Interface Specification

Endpoint designs must include a Swagger file (or files) that cover all HTTP operations and parameters for all Resources defined in the design.

Versioning

API Endpoints must be versioned as follows:

API Granularity of Versioning

Over time systems evolve, the features, functionality and data stored within them change, APIs need to evolve as a consequence. It is impractical to upgrade all client and server systems simultaneously on both sides of an API. Therefore, it is a necessary to specify an API version and carefully manage the supported versions of an API endpoint so that existing interoperability is not compromised. The purpose of versioning is to avoid breaking existing deployments when new client or service instances are deployed.

API Endpoints must be versioned independently from other endpoints. API Endpoints should cover the smallest reasonable set of related and indivisible Resources. API Endpoints MUST be versioned using a Major.Minor scheme, E.g. 4.5

Semantics of API Versioning

Endpoints must be versioned such that existing consumers (clients) will not be broken by changes made by a new Minor version. Minor changes can introduce new artefacts as long as the new Recipients can accept old content with old semantics.

Major changes can remove and add artefacts as required. There is no expectation of compatibility between different Major versions. Minor versions are backwards compatible; existing consumers can use newer API Endpoint versions that have the same Major version number.

Semantics of API Versioning Diagram

Minor Version Increment rules:

  1. Changes must be “client” backward compatible with the all ancestor Minor versions of the specification. Existing clients must be able to successfully interact with providers that support a later Endpoint minor version, without invalidating or changing the meaning (effect) of the interaction.
  2. Both syntactic and sematic backward compatibility must be maintained.
  3. Side-effects may be introduced in the service as long as they do not invalidate the behaviour of existing clients or services.
  4. The previous forms of artefacts within the specification must continue to be supported (although new optional structure may be introduced that would not be processed correctly by a preceding minor version recipient).
  5. New optional structures must be immaterial to recipients that do not understand them.

Major Version Increment rules:

  1. May be incompatible with previous version of the Endpoint design.
  2. Both backward and forward compatibility may be broken.
  3. Existing artefacts can be removed in a new major version
  4. New mandatory fields may be added in a new major version.

The following table specifies which types of change are allowed for Major and Minor version increments.

Major and Minor Version Incrememnts Diagram

<
API Change Major Minor
Add a new resource to the endpoint Allowed Allowed
Add new view resource to the endpoint Allowed Allowed
Add a new expand field support to a resource Allowed Allowed
Add a new sort field support to a resource Allowed Allowed
Add a new filter field support to a resource Allowed Allowed
Add a new optional and ignorable field to a resource Allowed Allowed
Add a new optional but material field to a resource received by a client Allowed Disallowed
Add a new optional and client-ignorable field to a resource Allowed Allowed
Add a new optional but vital field to a resource Allowed Disallowed
Add a new mandatory field to a resourceAllowed Disallowed
Change the type (value space) of a field to a resource Allowed Disallowed
Support an additional content type for a resource Allowed Allowed
Change the default content type for a resource Allowed Disallowed
Change the default content type for a resource Allowed Disallowed
Enlarge the set of supported authorisation protocols Allowed Allowed
Remove a resource from an endpoint Allowed Disallowed
Remove a field from a resource Allowed Disallowed
Remove sort, expand, filter support from a Resource Allowed Disallowed
Remove support for a content type from a Resource Allowed Disallowed

The meaning of “optional but vital” is a data item that although optional in the document schema must be parsed and processed if present, thus “vital” to the processing of the request or response. Such fields are syntactically optional but not semantically ignorable (and therefor disallowed in minor version changes).

Consumer control over API Version used

When there are several published versions of an API Endpoint design then each environment could potentially have several providers deployed at one time each supporting different version. Provider implementations may support a single API Endpoint version, or they may support several API Endpoint versions. API Endpoint Consumers can select the Major version that they are compatible with and wish to utilise.

The major version is embedded in the URI of a Resource, for example: https://api.londonmarketgroup.co.uk/DelegatedAuthority/Reinsurance/v1/quotes

Consumers must automatically be routed by the API gateway to the latest minor version that exists for the major version that is specified in the URI. Only a single Minor version needs to be supported per major version (as the others are not addressable and cannot be invoked).

As no backwards compatibility is provided between major versions, implementations must not provide or support an automatic latest alias version in the URI. There shall be no way of addressing specific minor versions of the API Endpoint.

Provider Implementation Version

API Endpoints are implemented by a provider. The implementation must have its own versioning scheme. The version of the provider implementation and the version of the API Endpoint must be distinct. The version of the provider implementation can be retrieved via a meta Resource that must exist for each endpoint.

Schema Versions

The versioning of XML and JSON schemas must be consistent with the overall API Endpoint version. Each Schema must contain a version number, this number must have the same major and minor version number as the API Endpoint does that reference those schemas.

This implies that a new version of schemas must be created for each new version of the API design.

The major.minor version value of the Endpoint version must be present in the XML and JSON schema version identifiers.

The XML namespace should not contain the major or minor version numbers within it. The XML namespace may be the same as the URI of the Endpoint.

Health

Every Endpoint must define a singleton Resource called “health” the Resource is to be placed immediately after the version path segment e.g: https://api.londonmarketgroup.co.uk/{capability}/{facility}/{versionNo}/health

The health resource may have JSON or XML representations but must have a textual format which is the default.

The health Resource must return a http response code of 200 Ok if the service determines that all the Resources within that endpoint version are operating correctly. The response content may be empty, but can contain human readable text that must not contain sensitive information.

The health Resource must return an http response code of 500 Internal Error if the service determines that any of the Resources within that endpoint version are not operating correctly. The response content may be empty, but should contain human readable text that must not contain sensitive information.

If a Resource within an Endpoint is operating correctly then any client should be able to successfully interact with the Resource or Resource Collection. “correct” operation does not imply normal performance levels or failure rates.

The maximum time that a client should have to wait for a reply (of the first byte of the response) to a request is defined in Constraints as 30 seconds. If a significant (defined by the Endpoint specification) fraction of the requests exceed this limit, then the Resource is not operating correctly.

Even in normal operation Resource HTTP requests occasionally fail with 5XX response code, clients should be written to handle these intermittent failures and retry the request.

A “Retry-After” response header may be returned with a 5XX (service unavailable) response code to indicate the expected service maintenance period.

Security

This specification mandates a series of rules for API Consumers and API Providers and the API Gateway.

All Calls from API Consumers to API Endpoints are mediated by the API Gateway. Each API Endpoint will have a corresponding API Provider that implements the Endpoint specification. All Calls from Consumers must be directed at the API-GW which will have a well-known DNS Domain for each environment where it is deployed. This is covered under Environments.

Each party has specific set of security rules that must be observed.

API Consumer Security Rules

API Consumers must provide two separate identifying security tokens.

The first identifies the calling application and is achieved via mutual HTTPS authentication. The API Consumer (client) must initiate a HTTPS connection to the API Gateway with the inclusion of a (client) X.509 Certificate. The HTTPS protocol will ensure that the X.509 certificate is valid and the client (or its reverse proxy) has access to the private key for the X.509 Certificate. The CN of the Subject Field in the X.509 Certificate will be used to identify the calling application. The Certificate must be signed by a trusted CA (One listed by the Microsoft Trusted Root Certificate Program). The Certificate should be an Extended Validation Certificate.

Secondly the HTTP request must include an “Authorization” request header with a JSON Web Token (JWT) as follows: Authorization: Bearer

The JWT in the Authorization header must be signed by a Security Token Service (STS) that is known to the API Gateway.

The JWT must be an “on-behalf-of” token, that is; the JWT must be issued to the calling application. JWT’s returned from an OAuth2.0 login are not normally “on-behalf-of” tokens. The JWT MUST contain a claim called “scp” and it must have the value of “user_impersonation”.

The claims that may be understood by the API are listed in Appendix - JWT Claims. Other claims in the JWT will be ignored. Claims marked as mandatory must be present in the JWT supplied by the API Consumer.

The presence of an “amr” claim with a value of “mfa” must mean that multi-factor authentication has taken place.

API Gateway Security Rules

The API Gateway must support an HTTPS connections with a X.509 certificate. The certificate must be signed by a trusted CA (One listed by the Microsoft Trusted Root Certificate Program). The Certificate MUST be an Extended Validation Certificate.

The API Gateway acts as a Policy Enforcement Point (PEP). Incoming requests to the Gateway are authenticated against:

  1. the client X.509 certificate presented on (mutual auth) HTTPS setup,
  2. the JWT in the HTTP “Authorization” request header.

The API Gateway MAY perform high level authorisation, but should not perform low level account role based authorisation.

When authentication or authorisation fail the API Gateway must respond with a 401 response code and a message indicating which PEP step led to the failure.

Details of the PEP steps taken are described in “API Gateway Security Rules 1.0” document which is released in conjunction with this document.

Once the PEP checks have been completed then the API-GW creates a new JWT using information collected during the enforcement checks along with values from the incoming JWT. This new JWT will include the incoming JWT in the claim “lmg_pkt”. The new JWT WILL be signed. The new JWT is then placed in the HTTP Authorization header (as per div 5.12.1) in the HTTPS request to the correct API Provider. The CN of the signing certificate will be ‘api.londonmarketgroup.co.uk’. A file MUST be made available at the well-known URI of ‘https://api.londonmarketgroup.co.uk/discovery/.well-known/openid-configuration’, this file must reference a JWKS file. The JWKS file must contain a encoded x509 certificate that can be used to validate the JWT signature. The ‘openid-configuration’ and the ‘jwks.json’ file must follow the rfc7515 standard sufficiently to support verification of the JWT signature.

The outgoing HTTP connection to the API Provider will utilise a client X.509 Certificate if requested by the provider http server, the subject of the certificate will have a CN value that matches the DNS Domain of the API-GW (e.g. api.londonmarketgroup.co.uk).

API Provider Security Rules

An API Provider must support a HTTPS connections with a X.509 certificate. The certificate mustbe signed by a trusted CA (One listed by the Microsoft Trusted Root Certificate Program).

The API Provider must only allow incoming calls over HTTPS. The API provider mayrequite HTTPS session setup with a client certificate. When a client certificate is requested by the provider the API-GW mustprovide a client certificate. The API-GW client certificate subject’s CN value mustmatch the DNS Domain of the API-GW.

If the API Provider did not authenticate the gateway using the client certificate then it must:

  1. check that a well formed JWT is present in the authorization http request header,
  2. check that the JWT has been signed by a x509 key found via the well-known URI of ‘https://api.londonmarketgroup.co.uk/discovery/.well-known/openid-configuration’ and that the certificate has a CN value of ‘signing-api.londonmarketgroup.co.uk’.
  3. check that the JWT has not expired.
  4. check that the JWT has an ‘iss’ claim and that it matches the expected URI of the gateway.
  5. check that the JWT has an ‘aud’ claim and that value matches the endpoint URI up to but not including the version.

The JWT may contain the following additional claims:

appid, aud, amr, given_name, idp, iat, family_name, unique_name, oid, sub, scp, nbf, exp, upn, lmg_mpo, lmg_cert_dn, iss, lmg_pkt

The API Provider may use any field in the JWT for authorisation purposes.

Sub Meaning
sub Identifies the principal about which the token asserts information, such as the user of an application. This value is immutable and cannot be reassigned or reused, so it can be used to perform authorisation checks safely. This value should remain constant even when the email address of the principle changes.
upn The identity of the principle as an email address. This value may change over the lifetime of the individual.
amr A list of authentication methods used. The presence of “mfa” in the list indicates that Multi factor authentication took place.
lmg_mpo A JSON stricture containing the details of the MPO: The value will be as follows: { “MPOCode” : “{MPO.MPOCode}”, “OrgName” : “{MPO.OrganisationName}” }
lmg_cert_dn The CN value from the Subject from the client certificate presented to API-GW in the HTTPS request. This value indicates the identity of the application that is invoking the API on behalf of the principle.
lmg_pkt The JWT that was received by the API gateway from the Consumer.

Providers should not use values of unique_name, family_name or given_name for authorisation purposes as these claims are options and not guaranteed to be present in all JWTs.

Only URIs matching patterns specified in the Endpoint design are allowed to be processed by the API implementation. API Providers must validate the structure and query parameters in all request URIs.

API Providers may store and log values from the JWT but must comply with GDPR regulations as several fields contain personal information.

Health Resource

The security rules mentioned in API Consumer Security Rules, API Gateway Security Rules and API Provider Security Rules above are relaxed in a single case. Each API Endpoint includes a Health Resource. Calls to any /health Resource can be:

  1. Made by API Consumers without use of HTTPS client certificates.
  2. Offered by API Providers over HTTP.
  3. Made by API Consumers without inclusion of a JWT.
  4. Passed through the API-GW without PEP checks.

The API Gateway may choose to response with cached responses to Heath Resources. The cache timeout should be less than 100 seconds.

The API Gateway may choose to implement defence measures against DoS attacks against the Health Resources (such as ignoring a Cache-Control: no-cache request headers). Care should be taken in the API provider implementation such that the Health resources do not become additional DoS vectors.

Version Resource

The singleton version Resource that exists for each endpoint must implement security checks just like any other Resource in the endpoint design. The minimum authorisation required to call any other resource in the endpoint design (except /health) must be the minimum authorisation required to call the /version Resource.

Environments

The API consumers and producers (client and services) can be deployed to various environments. Each environment is used for one or more specific development purposes, such as production, testing or integration.

The environment must be encoded in the URI of every Resource.

The environment will be encoded in the prefix of the domain name of the URI, for example:

  • api.londonmarketgroup.co.uk
  • preprod-api.londonmarketgroup.co.uk
  • sand-api.londonmarketgroup.co.uk

The URIs for APIs will match one of the patterns below:

  • https://sand-api.londonmarketgroup.co.uk/{capability}/{facility}/{versionNo}/{Resource}
  • https://preprod-api.londonmarketgroup.co.uk/{capability}/{facility}/{versionNo}/{Resource}
  • https://api.londonmarketgroup.co.uk/{capability}/{facility}/{versionNo}/{Resource}

Environmental Security Restrictions

Each of the environments are completely separate and distinct instances with different certificates.

No JWT from one environment should pass the PEP checks performed by the API-GW of another environment. It must not be possible for an API Consumer in one environment to be able to successfully call an API in another environment.

The Consumer client certificate names must be different between each environment.

The domain name for each environment must be used throughout including the values within a JWT. For example the “iss” claim value must be set to “https://sand-api.londonmarketgroup.co.uk/” for all JWT’s created by the API gateway in the sandbox environment.

Published Artefacts

When designing an API Endpoint the result is a set of human and machine readable documents.

The following documents are published:

  1. Overarching Endpoint design
  2. The Logical Information model
  3. The Resource model
  4. Any common schemas
  5. A set of schema documents that collectively define the Resource documents for each supported structured content type
  6. A set of API specification documents that collectively define the Resources in the Endpoint

Constraints

Although many parts of an API in both the specification and the operation many not have bounds defined by the standards, there many exist practical limits that if exceeded will lead to failure.

The following table list the general constrains that are true for all resources.

Constraint Name Role Limit Notes
Maximum Class/Resource name length Endpoint designer 80 characters
Maximum URI length Endpoint provider & Endpoint consumer 14,000 characters URIs longer than this may be rejected by the API-GW or the endpoint provider.
Maximum URI path length Endpoint provider 260 Characters URIs with paths longer than this may be rejected by the API-GW or the endpoint provider. This restriction limits the maximum length of the Resource ID (primary key) segment to be no larger than: 260 –
Request timeout Endpoint consumer 30 seconds Consumer should wait at least 30 seconds before timing out a request.

Appendices

Appendix - Identity

XML

Each Resource is represented by an XML Element. The identity of the Resource is held in an attribute of the root element.

JSON

Each Resource is represented as JSON document. The top level JSON object (dictionary) contains a name of “id” with a value that is the identifier for the Resource.

{
  "id": "kxgzi42i12l"
}

Each Resource (and optionally in embedded resources) may have a link structure that contains zero or more links. A link is a subset of the atom link structure as follows:

XML

Each Resource is represented by an XML Element. The links of the Resource are held in a child element of the root element.

JSON

{
  "_links": [
    {
      "rel": "canonical",
      "href": "https://sand-api.londonmarketgroup.co.uk/Lloyds/CatastropheCodes/v1/CatastropheCodes/17E"
    }
  ],
  "id": "17E",
  "Code": "17E",
  "Definition": "Typhoon Hato, 20 August 2017 and ongoing, affecting Hong Kong, Macau and South China",
  "EventStartDate": "2017-08-20",
  "EventYear": 2017
}

Appendix - Collection Wrapper Document

All Resource collections share a common document structure

XML

JSON

{
  "total": 2,
  "_links": [
    {
      "rel": "canonical",
      "href": "https://sand-api.londonmarketgroup.co.uk/Lloyds/CatastropheCodes/v1/CatastropheCodes?Code=17B,17D&_pageSize=200&_pageNum=1"
    }
  ],
  "items": [
    {
      "id": "17B",
      "Code": "17B",
      "Definition": "Tornadoes in South-Eastern United States, 7 February 2017",
      "EventStartDate": "2017-02-07",
      "EventEndDate": "2017-02-07",
      "EventYear": 2017
    },
    {
      "id": "17D",
      "Code": "17D",
      "Definition": "Tropical Cyclone Debbie from 27-28 March 2017. Debbie was downgraded to tropical low late on 28 March 2017 and the weather system continued to spread from QLD into NSW.",
      "EventStartDate": "2017-03-27",
      "EventEndDate": "2017-03-28",
      "EventYear": 2017
    }
  ]
}

Appendix - Version Document

The Version document has two fields the first is the APIVersionNumber that contains the version of the endpoint specification with both Major and Minor versions separated by a “.”.

The second field is the backend implementation version number that can have any textual format, although it should be recognisably a version number.

XML

JSON

{
  "APIVersionNumber": "3.1",
  "ImplementationVersion": "1.0.0.0"
}

Appendix - Health Document

The health resource is designed to be used by load balancers and other management layers to determine if the service is working correctly. If the service is working correctly then a 200 response code should be returned. The content returned is not material for the primary use of this resource, but may be used for logging and debugging.

If a XML document is returned then it should be as follows:

If a JSON document is returned then it can contain any valid JSON.

Appendix - Error Documents

Define a standard error document returned by all API calls that result in a 4XX or 5XX response code.

XML Error document:

JSON Error document:

{
  "Message": "Input string was not in a correct format.",
  "Code": 500
}

Appendix - Response Code Rules

GET Method

GET When Service Sends What Client Does
All 1XX Must never be used Log and continue with processing
200 Only when a GET request is successfully completed Continue with processing
204 When the service has no data to send to client Continue with processing.
Other 2XX Must never be use Log and continue with processing
301 Should not be used Should retry request with new URI.
302 Should not be used Should retry request with new URI.
304 May be used Client must use cached copy of Resource
307 May be used Must retry request with new URI
308 May be used Must retry request with new URIMust strore the redirection for future requests
Other 3XX Must never be use Must log and then discontinue processing
400 Must be sent back when the request cannot be completed due to the nature of the URI and the Resource state held by the service. Must not be sent when request fails due to some other reason. Must log and then discontinue processing
401 Must only be sent in response when a client identity has not been authenticated successfully Must log and then discontinue processing
403 Must only be sent in response when the Resource is not accessible to the client identity due to authorisation failure Must log and then discontinue processing
404 May be sent if URI does not support POST Mustlog and then discontinue processing. Future attempts to GET this URI are allowed
406 May be sent in the response when the Resource cannot be returned in an acceptable content types Must log and then discontinue processing
410 May be used. Same situation as 404 Must log and then retry or discontinue processing. Future attempts to GET this URI are allowed
414 May be sent back in response Must log and then discontinue processing
429 May be sent back in response Must log and either retry later or discontinue processing
Other 4XX Must never be used Must log and then discontinue processing
500 May be sent back in response if request timed out waiting for client request data Must log and then retry or discontinue processing. Future attempts to GET this URI are allowed
500 May be sent back when the request cannot be completed due to the service health or the request failing for a reason unrelated to the URI or the state held by the service. Must log and either retry later or discontinue processing
501 Must be sent back when the request cannot be completed due to limitations of the implementation Must log and then ether discontinue processing or fall back to a simpler URI
502 May be sent back by API Gateway when upstream service response is incomplete or unintelligible Must log and either retry later or discontinue processing
503 Must be sent back when the request cannot be completed due to the service health or service is down.be sent back by API Gateway when upstream service response is incomplete or unintelligible Must log and either retry later or discontinue processing
504 Must be sent back by API gateway when request to upstream service times out Must log and either retry later or discontinue processing
Other 5XX Should never be used Must log and then discontinue processing

PUT Method

GET When Service Sends What Client Does
Other 1XX Must never be used. Log and continue with processing.
200 May be used when a PUT request is successfully completed. Continue with processing.
201 Must not be used when a PUT request is successfully completed. Log and continue with processing.
204 May be used when a PUT request is successfully completed. Continue with processing.
Other 2XX Must not be used. Log and continue with processing.
301 Should be used. Should retry request with new URI.
302 Should not be used. Should retry request with new URI.
307 May be used. Must retry request with new URI.
308 May be used. Must retry request with new URI. May store the redirection for future requests.
Other 3XX Must NOT be used. Must log and then discontinue processing
400 Must be sent back when the request cannot be completed due to the nature of the URI and the Resource state held by the service. Must not be sent when request fails due to some other reason. Must log and then discontinue processing
401 Must only be sent in response when a client identity has not been authenticated successfully Must log and then discontinue processing
403 Must only be sent in response when the Resource is not accessible to the client identity due to authorisation failure Must log and then discontinue processing
404 Must be sent in response when the Resource specified in the URI does not exist. Must log and then discontinue processing. Future attempts to GET this URI are allowed
405 May be sent if URI does not support PUT Must log and then discontinue processing
408 May be sent back in response if request timed out waiting for client request data. Must log and then retry or discontinue processing. Future attempts to GET this URI are allowed
409 May be sent back in response if edit conflict has occurred Must Log and then client can either discontinue or retry after retrieving latest Resource state.
410 May be used. Same situation as 404 Must log and then discontinue processing. Future attempts to GET this URI are allowed
412 Must be returned when a If-Unmodified-Since or an If-Match precondition fails in a PUT request. When precondition check fails on the server and 412 is returned the client must log the occurrence and may choose to retry by performing a GET to retrieve the latest resource state then merge the state within the client and retry the business logic (leading to a new PUT).
414 May be sent back in response. Must log and then discontinue processing
429 May be sent back in response. Must log and either retry later or discontinue processing.
Other 4XX Must never be used. Must log and then discontinue processing
500 May be sent back when the request cannot be completed due to the service health or the request failing for a reason unrelated to the URI or the state held by the service. Must log and either retry later or discontinue processing.
501 Must be sent back when the request cannot be completed due to limitations of the implementation. Must log and then ether discontinue processing or fall back to a simpler URI.
502 May be sent back by API Gateway when upstream service response is incomplete or unintelligible. Must log and either retry later or discontinue processing.
503 Must be sent back when the request cannot be completed due to the service health or service is down. Must log and either retry later or discontinue processing.
504 Must be sent back by API gateway when request to upstream service times out. Must log and either retry later or discontinue processing.
Other 5XX Should never be used. Must log and then discontinue processing

POST Method

POST When Service Sends What Client Does
Other 1XX Must never be used Log and continue with processing
200 May be used when a PUT request is successfully completed Continue with processing
201 Must Not be used when a PUT request is successfully completed Log and continue with processing
204 May be used when a PUT request is successfully completed Continue with processing
Other 2XX Must Not be used Log and continue with processing
301 Should not be used Should retry request with new URI
302 Should Not be used Should retry request with new URI

307

May be used Must retry request with new URI
308 May be used Must retry request with new URI. May store the redirection for future requests
Other 3XX Must not be used Must log and then discontinue processing
400 Must be sent back when the request cannot be completed due to the nature of the URI and the Resource state held by the service. Must not be sent when request fails due to some other reason Must log and then discontinue processing
401 Must only be sent in response when a client identity has not been authenticated successfully Must log and then discontinue processing
403 Must only be sent in response when the Resource is not accessible to the client identity due to authorisation failure Must log and then discontinue processing
404 Must be sent in response when the Resource specified in the URI does not exist Must log and then discontinue processing. Future attempts to GET this URI are allowed
405 May be sent if URI does not support POST Must log and then discontinue processing
408 May be sent back in response if request timed out waiting for client request data Must log and then retry or discontinue processing. Future attempts to GET this URI are allowed
409 May be sent back in response if edit conflict has occurred Must log and then client can either discontinue or retry after retrieving latest Resource state
410 May be used. Same situation as 404 Must log and then discontinue processing. Future attempts to GET this URI are allowed
413 May be sent back if the payload was too large Must log and then discontinue processing
414 May be sent back in response Must log and then discontinue processing
429 May be sent back in response Must log and either retry later or discontinue processing
Other 4XX Must never be used Must log and then discontinue processing
500 May be sent back when the request cannot be completed due to the service health or the request failing for a reason unrelated to the URI or the state held by the service Must log and either retry later or discontinue processing
501 Must be sent back when the request cannot be completed due to limitations of the implementation Must log and then ether discontinue processing or fall back to a simpler URI
502 May be sent back by API Gateway when upstream service response is incomplete or unintelligible Must log and either retry later or discontinue processing
503 Must be sent back when the request cannot be completed due to the service health or service is down Must log and either retry later or discontinue processing
504 Must be sent back by API gateway when request to upstream service times out Must log and either retry later or discontinue processing
Other 5XX Should never be used Must log and then discontinue processing

DELETE Method

DELETE When Service Sends What Client Does
Other 1XX Must never be used Log and continue with processing
200 Only when a DELETE request is successfully completed Continue with processing
204 May be used when a DELETE request is successfully completed Continue with processing
Other 2XX Must never be used Log and continue with processing
301 Should not be used Should retry request with new URI
302 Should not be used Should retry request with new URI
307 May be used Must retry request with new URI
308 May be used Must retry request with new URI May store the redirection for future requests
Other 3XX Must never be used Must log and then discontinue processing
400 Must be sent back when the request cannot be completed due to the nature of the URI and the Resource state held by the service. Must not be sent when request fails due to some other reason Must log and then discontinue processing
401 Must only be sent in response when a client identity has not been authenticated successfully Must log and then discontinue processing
403 Must only be sent in response when the Resource is not accessible to the client identity due to authorisation failure Must log and then discontinue processing
404 Must be sent in response when the Resource specified in the URI does not exist. This includes the case where the Resource has been deleted by a previous DELETE method Must log and then discontinue processing
410 May be used Same situation as 404 Must log and then discontinue processing Future attempts to GET this URI are allowed
414 May be sent back in response Must log and then discontinue processing
429 May be sent back in response Must log and either retry later or discontinue processing
Other 4XX Must never be used Must log and then discontinue processing
500 May be sent back when the request cannot be completed due to the service health or the request failing for a reason unrelated to the URI or the state held by the service Must log and either retry later or discontinue processing
501 Must be sent back when the request cannot be completed due to limitations of the implementation Must log and then ether discontinue processing or fall back to a simpler URI
502 May be sent back by API Gateway when upstream service response is incomplete or unintelligible Must log and either retry later or discontinue processing
503 Must be sent back when the request cannot be completed due to the service health or service is down Must log and either retry later or discontinue processing
504 Must be sent back by API gateway when request to upstream service times out Must log and either retry later or discontinue processing
Other 5XX Should never be used Must log and then discontinue processing

Appendix - Multipart Resource Example Endpoint Rules

The table below details the Resource URIs supported for a combined structured and unstructured Resources.

This is an example only and does not describe a real-life Resource.

File URI Pattern Operation Rules
https://apilondonmarketgroupcouk/ CS/SDE/v1/SharedFiles GET The Collection Resource returns either application/json or application/xml depending on the Accept header in the request. The file content is not returned in the response only the metadata.
https://apilondonmarketgroupcouk/ CS/SDE/v1/SharedFiles POST A new Shared File Resource is created Expects multipart/form-data mime type. The first part must be either application/json or application/xml. The second part can be any mime type and is the content of the file.
https://apilondonmarketgroupcouk/ CS/SDE/v1/SharedFiles/{id} GET Returns a Multipart Mime message. The first mime part is application/json the second will be the mime type of the file content.
https://apilondonmarketgroupcouk/ CS/SDE/v1/SharedFiles/{id} PUT Expects either application/json or application/xml mimetype and replaces the metadata of the Resource. The content part remains unchanged.
https://apilondonmarketgroupcouk/ CS/SDE/v1/SharedFiles/{id}/content GET Returns a single part Mime message. The mime type will be the mime type of the file content. The Accept header must contain ‘*/*’ implementations may be able to convert to other types depending on the file mime type.
https://apilondonmarketgroupcouk/ CS/SDE/v1/SharedFiles/{id}/content PUT Expects a single part mime type eg ‘image/jpeg’. The content of the Resource will be replaced with the payload.

Appendix - JWT Claims

JWTs are Bearer tokens that are placed in the Authorisation header of the HTTPS requests.

Claims in JWTs must follow the Azure AD nomenclature as described in https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-token-and-claims

The following claims are recognized by the API-GW PEP:

ID Full Name Description Mandatory Allowable Values Semantics Example
appid Application ID Identifies the application that is using the token to access a resource. The application can act as itself or on behalf of a user. The application ID typically represents an application object, but it can also represent a service principal object in Azure AD. True Either 1. the GUID of the Application in the CID AAD Tenant 2. A URI for non AAD STS. "appid": "c0922757-1b8e-4d94-ae8f-09e68a0af381",
aud Audience The intended recipient of the token. The application that receives the token must verify that the audience value is correct and reject any tokens intended for a different audience. True The URI of the API gateway. The URI may include the path of the endpoint. "aud" : "https://api.londonmarketgroup.co.uk" "aud" : "https://api.londonmarketgroup.co.uk/Lloyds/MarketParticipantRegistry"
amr Authentication Method Identifies how the subject of the token was authenticated. May be empty. True If STS is asserting that MFA has been performed then the list SH contain at least two other values. "amr": ["pwd"] "amr": ["mfa",""pwd","pop"]
given_name First Name Provides the first or "given" name of the user. False A given name. "given_name": "Joe"
idp Identity Provider Records the identity provider that authenticated the subject of the token. This value is identical to the value of the Issuer claim unless the user account is in a different tenant than the issuer. False The URI of the market participant STS. If absent then the user identity is local to the Issuer "idp":"https://sts.windows.net/8df4b91e-bf72-411d-9902-5ecc8f1e6c11/"
iat Issued At Stores the time at which the token was issued. It is often used to measure token freshness. Must be in GMT. True A numeric value representing the number of seconds from: 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. "iat": 1390234181
iss Issuer Identifies the security token service (STS) that constructs and returns the token. In the tokens that Azure AD returns, the issuer is sts.windows.net. The GUID in the Issuer claim value is the tenant ID of the Azure AD directory. The tenant ID is an immutable and reliable identifier of the directory. True Either 1. The CID AAD tenant URI 2. The URI of the market participant STS "iss":"https://sts.windows.net/20c3f8e2-b4e7-49d5-9d17-6e7939566da1"
family_name Last Name Provides the last name, surname, or family name of the user as defined in the Azure AD user object. False A family name. "family_name": "Bloggs"
unique_name Name Provides a human readable value that identifies the subject of the token. This value is not guaranteed to be unique within a tenant and is designed to be used only for display purposes.  False Email address of user being identified with this token. "unique_name": "kelvin@grumble.com"
oid Object ID Contains a unique identifier of an object in Azure AD. This value is immutable and cannot be reassigned or reused. Use the object ID to identify an object in queries to Azure AD. False A UUID. "oid":"528b2ac2-aa9c-45e1-88d4-959b53bc7dd0"
lmg_ptk Ancestor JWT Contains the JWT that was input to the process of creating the containing JWT. False A complete JWT. 3 base64 strings concatenated with ‘.’. "ptk" : " eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiJj MDkyMjc1Ny0xYjhlLTRkOTQtYWU4Zi0wOWU2OGEwYWYzODEi LCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC84ZGY0 YjkxZS1iZjcyLTQxMWQtOTkwMi01ZWNjOGYxZTZjMTEvIiwi aWF0IjoxNTE5NjQ5ODg5LCJuYmYiOjE1MTk2NDk4ODksImV4 cCI6MTUxOTY1NDA4NCwiYW1yIjpbInB3ZCJdLCJmYW1pbHlf bmFtZSI6IlZlbGxpbmdpcmkiLCJnaXZlbl9uYW1lIjoiUHJh Ymh1IiwiaXBhZGRyIjoiODIuNy4xNzUuOTQiLCJuYW1lIjoi VmVsbGluZ2lyaSwgUHJhYmh1Iiwib2lkIjoiNmJkMjgyYWMt MTQ1NS00NzkxLTkxMGYtYTk3M2VmMzAzMWFjIiwib25wcmVt X3NpZCI6IlMtMS01LTIxLTI3MTI1NDUwMTAtNTE5NjQ5MDYt MTg3NTEzOTcxMS02MzQ5MyIsInN1YiI6IlJ0d1RqVWlpWDlD WTRzOUREajV2bUVZTnUwNTRkX1dBUmFFZE9OTnQzSmsiLCJ0 aWQiOiI4ZGY0YjkxZS1iZjcyLTQxMWQtOTkwMi01ZWNjOGYx ZTZjMTEiLCJ1bmlxdWVfbmFtZSI6IlZlbGxpbmdQQGxsb3lk cy5jb20iLCJ1cG4iOiJWZWxsaW5nUEBsbG95ZHMuY29tIiwi dmVyIjoiMS4wIn0"
sub Subject Identifies the principal about which the token asserts information, such as the user of an application. This value is immutable and cannot be reassigned or reused, so it can be used to perform authorisation checks safely. True Unique identifier for user persistent across email changes.
scp Scope Indicates the impersonation permissions granted to the client application. The default permission is user_impersonation True user_impersonation "scp" : "user_impersonation"
nbf, exp Not Before, Expiry Defines the time interval within which a token is valid. The service that validates the token should verify that the current date is within the token lifetime, else it should reject the token. The service might allow for up to five minutes beyond the token lifetime range to account for any differences in clock time ("time skew") between Azure AD and the service True A numeric value representing the number of seconds from: 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. "nbf":1363289634, "exp":1363293234
upn User Principal Name Stores the user name of the user principal. False Email address of user being identified with this token. "upn": "joe@bloggs.net"
email Email Address Stores the user name in the form of an email address of the user principal. False Email address of user being identified with this token. "email": "joe@bloggs.net"

At least one of upn claim or email claim must be present in JWT sent to API gateway.

Appendix – Character Encoding and Decoding in Resource URIs

When clients construct URIs according to the patterns described in the Endpoint Designs they must take care to encode certain characters so that resulting URI is valid according to the URI standard, and are not ambiguous to receiving services.

URIs are defined by this document: https://www.ietf.org/rfc/rfc3986.txt

URIs are made up of a limited set of characters drawn from the US-ACSII character set. Which include digits letters and a few symbols. Certain characters are used for special purposes on are only allowed in certain places in a URI. Where a character that need to be inserted into the URI and is outside the allowed set or is one of the special characters (not being used for its special purpose) the character MUST be encoded using the % encoding scheme.

Please refer to section 2.2 "Reserved Characters" in rfc3986. – "These characters are called 'reserved" because they may (or may not) be defined as delimiters by the generic syntax, by each scheme-specific syntax, or by the   implementation-specific syntax of a URI's dereferencing algorithm. If data for a URI component would conflict with a reserved character's purpose as a delimiter, then the conflicting data must be percent-encoded before the URI is formed."

When Endpoints are being designed, careful consideration MUST be made where characters in the URIs have special meaning that could be in conflict with data values that need to be inserted when constructing a URI. API Endpoints SHOULD use characters from the reserved character list where such special character are required within a URI pattern.

Extreme care during design and extensive testing must be adhered to when supporting the following characters in the primary key: ‘/’, ‘\’, and ‘+’. Many web servers and http libraries treat these characters specially and may prove difficult to implement successfully. Issue have been seen when the characters are encoded correctly in the URI.

This document defines generic filter expressions for describing filters that match sets of values (5.6 Collection Filtering) the special character used are "!", "(", ")" and ",". Where data values contain these characters the client constructing the URI MUST encode them using % encoding.

From rfc3986 – "URI producing applications should percent-encode data octets that correspond to characters in the reserved set unless these characters are specifically allowed by the URI scheme to represent data in that component."

For example:

            A collection ABC has a field called ‘Foo’ of type string that supports the generic query filtering.

An example query using filtering on ‘Foo’ might be:

            https://api.londonmarketgroup.co.uk/LIMOSS/ABC?Foo=match_casesens(AA,BB,CC)

The above URI would return the Resources that have one of the values "AA", "BB" or "CC" in the field ‘Foo’.

If a client wanted to get ABC Resource that had one of the values "(", ")" or "," in the field ‘Foo’ then the client MUST encode ‘(‘ as "%28", ")" as %29 and ‘,’ as %2C so the resultant URI would be:

            https://api.londonmarketgroup.co.uk/LIMOSS/ABC?Foo=match_casesens(%28,%29,%2C)

Similarly when creating a URI for a singleton GET, the characters in the key that are on the reserved list SHOULD be encoded by clients and in some cases MUST be encoded to avoid changing the meaning of the resultant URI.

Provider Implementations MUST decode URIs correctly and not confuse unencoded with encoded reserved characters.

The following table details which characters found in data that are to be used as query filter values must be encoded using % encoding:

Characters Encoding when used in query string filter value Comment / ABNF reference
a-z None unreserved
A-Z None unreserved
0-9 None unreserved
"-" / "." / "_" / "~" None unreserved
":" / "@ None (optionally may be encoded) Allowed in segment
"$" / "'" / "*" / "+" / ";" / "=" None (optionally may be encoded) sub-delimsminus String Filter query characters
"/" / "?" None (optionally may be encoded) query
"#" / "[" / "]" Must be encoded gen-delims minus ":" / "@
"!" / "," / "&" / "(" / ")" Must be encoded String Filter query characters
"%" Must be encoded pct-encoded
All Others Must be encoded

The following table details which characters found in data that are to be used as the key value in a singleton GET must be encoded using % encoding:

Characters Encoding when used in singleton GET in key value Comment / ABNF reference
a-z None unreserved
A-Z None unreserved
0-9 None unreserved
"-" / "." / "_" / "~" None unreserved
":" / "@ None (optionally may be encoded) pchar
"!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" None (optionally may be encoded) sub-delims
"#" / "/" / "?" / "[" / "]" Must be encoded gen-delims minus ":" / "@
"%" Must be encoded pct-encoded
All Others Must be encoded