OpenAPI Specs

Akoya provides secure (TLS v1.2) access to RESTful APIs that are based on the API/Data Structures as defined by the Financial Data Exchange. All data requests use standard GET and POST methods and must include authorization in the header. All responses are returned in JSON format.

OpenAPI tools

Tools such as Stoplight Studio, Swagger UI, or your choice of editors may be used.

If using Swagger UI through a browser without a proxy, the Akoya endpoints will return a CORS error such as: No Access-Control-Allow-Origin header is present on the requested resource. For more information, see CORS Requirements for "Try It Out" | SwaggerHub.

Tips for code generation

If using a code generator that strictly parses enums, please be aware that data retrieved through the Akoya network may have unknown enums and configure your generator appropriately.

For instance, if generating Java code with openapi-generator, consider setting enumUnknownDefaultCase = true in your configuration. See: openapi-generator/java.md

The Akoya API specification uses anyOf and oneOf keywords to indicate data is valid against any of or one of the specified schemas. Some code generation tools have difficulty with these keywords. A workaround for code generation may be to replace oneOf and anyOf keywords with allOf.

Converting specs to 3.0

Among other new features, OpenAPI 3.1.0 introduced the ability to include more than one code example for a schema object:

content:  
  application/json:  
    example:  
      accountId: '753961248'  
      accountType: 'Savings'

content:  
  application/json:  
    examples:  
      Example 1:  
        accountId: '468172593'  
        accountType: 'Checking'  
      Example 2:  
        accountId: '372491586'  
        accountType: 'Brokerage'

Akoya has adopted OpenAPI v3.1.0 to leverage the ability to use more than one example. If you need to down-convert to 3.0.0, update the examples with one of the following methods:

• Remove ALL examples from the spec’s yaml file.

• Modify the schema object to include one example using the 3.0.0 syntax.

Process

• Change the version (first line of the file) from openapi: 3.1.0 to openapi: 3.0.0:

openapi: 3.0.0  
info:  
  title: Akoya APIs v2  
  version: '2.0'  
  summary: Akoya API v2

• Search the yaml file for instances of the examples: property.

• Delete all instances of examples: and their child properties.

OR:

• To keep one example in a schema object, select the example you want to keep and delete the others in the object. Then, change examples: to example: and remove the title property.

content:  
  application/json:  
    example:  
      accountId: '468172593'  
      accountType: 'Checking'

Change log