OpenAPI Specs

Akoya provides secure (TLS v1.2) access to RESTful APIs. These APIS are based on the API and data structures defined by FDX. All data requests use standard GET and POST methods and require authorization in the header. The APIs return responses in JSON format.

OpenAPI Tools

You can use tools such as Stoplight Studio, Swagger UI, or your choice of editors.

If you're using Swagger UI through a browser without a proxy, the Akoya endpoints returns 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, 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:

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:

• 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.