Onfido OpenAPI specification

Introduction

This specification supports the latest version of the Onfido API (v3.6).

It can also be used for generating client libraries to allow backend services to interact with the Onfido API. A Postman collection is provided as well for user's convenience.

Client libraries

Client libraries are built by Onfido in 5 different programming languages.

Nevertheless, users can generate libraries in any other language supported by the OpenAPI Generator.

How to use pre-built client libraries

The libraries below are generated and maintained by Onfido:

• onfido-java
• onfido-node
• onfido-php
• onfido-python
• onfido-ruby

Libraries come with Webhook Events validation and the possibility to easily choose a region to target.

Please find more information regarding how to use each library within their own README.md file.

How to build client libraries yourself

Please find in OpenAPI Generator documentation how to build client libraries and all the supported programming languages to build client libraries.

The file openapi.yaml should be provided to the generator.

We recommend providing the generator with the options below (whenever available):

enumUnknownDefaultCase: true
useOneOfDiscriminatorLookup: true
legacyDiscriminatorBehavior: false
disallowAdditionalPropertiesIfNotPresent: false

API Documentation

The openapi-reference/openapi.json file can be used to explore the OpenAPI definition with tools like Swagger Editor.

A pre-compiled Postman collection is also available in the Onfido documentation portal.

Development

Most of the contents in client libraries are auto-generated using OpenAPI Generator.

Generation is controlled by configuration and template files stored in each generator's folder.

Exclusion lists

A few exceptions come from a global exclusion list (defined as part of the rsync command in github workflow and sync-lib.sh script):

• /.git*
• /CHANGELOG*
• /.openapi-generator-ignore
• /.openapi-generator/FILES

For each generator, additional exclusions are defined into specific exclusions.txt files stored in each generator's folder.

Code is automatically generated into the generated/artifacts subfolders and pushed to each client library repository via automatically generated PRs. Every path matching the exclusion lists defined above is neither copied from artifact folder nor removed from the target client library repository: that’s the way for avoid pushing some contents to client libraries but also avoiding some files (tests and git files) from being removed or overridden.

A few files are automatically generated and committed in the generated/artifacts folder at PR merge time.

Configuration files

Configuration files are named config.yaml and allow for the provision of custom parameters to each generator. Most parameters are defined in the OpenAPI generator documentation. A global configuration (common/config.yaml) is used to store common parameters and share them among the different generators. Configuration files also include some variables (e.g. ${GENERATOR_NAME}) which are replaced before being provided to the Openapi generator (see envsubst command in generate.sh).

Templates

Templates are provided to add particular features to client libraries:

• Webhook Events validation
• Region selection
• Token provisioning
• Customisation of README.md files
• Access to common/custom report sections (when needed)
• Additional libraries for testing (when needed)

In nearly all cases, with the exception of Webhook Event Validation and README.md templates, mustache comments ({{!...}} ) are used to denote modified sections in templates.

Updating OpenAPI generator version

To update the OpenAPI generator version, bump the version in both update-specs-and-client-libraries.yaml and generate.sh. Afterwards run the ./shell/generate.sh script as usual, some errors like below might be raised:

 !!! Error while building generator ...!!!

 SHA256SUM for template ... changed, diff reported below. To overwrite template, run:
 ...

This happens when templates we're overriding have been updated. The script automatically fixes checksums for one generator at each run, but the templates need to be carefully reviewed and updated by following the procedure below:

1. Check which files have changed, by running git diff generators/**/templates/SHA256SUM
2. Compare each file with the one that has been freshly generated, e.g. if libraries/okhttp-gson/ApiClient.mustache checksum has been denoted as modified for java/okhttp-gson generator:

   diff generators/java/okhttp-gson/templates/libraries/okhttp-gson/ApiClient.mustache  generated/templates/java/okhttp-gson/libraries/okhttp-gson/ApiClient.mustache

3. Add all changes from the new version except the ones noted by mustache comments (i.e. {{! }})
4. Commit changes to both templates and SHA256SUM files

The changes to README.md should be carefully reviewed by comparing generated/templates/**/README.mustache files created with different OpenAPI generator versions.

Contributing

Repository is open to external contributions. At this end please:

1. Fork repository

2. Create your feature branch (git checkout -b my-new-feature)

3. Make your changes, see below sections for project setup and testing.

4. To update one (or more) client libraries, clone them in the parent folder so that all the onfido-* repositories lie at the same level. Then run the script ./shell/generate.sh in the onfido-openapi-spec folder and ./shell/sync-lib.sh in each of the client libraries' folder, as in the examples below:

   ../onfido-openapi-spec/shell/sync-lib.sh java java/okhttp-gson
   ../onfido-openapi-spec/shell/sync-lib.sh php

5. To verify changes to the OpenAPI definition with external tools, run:

   ./shell/refresh-openapi-spec-for-documentation.py \
           generated/artifacts/openapi/openapi.json \
           generated/artifacts/openapi-documentation/openapi.json

6. Before committing your changes, run the script ./shell/run-prettier.sh

7. Commit your changes (git commit -am 'Add some feature')

8. Push to the branch (git push origin my-new-feature)

9. Create a new Pull Request

Client libraries release (internal use only)

Described below is the procedure on how to deliver new client libraries:

1. Merge all the requested PRs in onfido-openapi-spec and wait for each workflow completion

2. Draft a new onfido-openapi-spec release using as Release title last released version bumped accordingly to the type of change(s) (vMAJOR.MINOR.PATCH):

   Type	Description
   Patch	changes not involving the OpenAPI spec (e.g. template)
   Minor	backward compatible changes to the OpenAPI spec
   Major	non-backward compatible changes to the OpenAPI spec

3. Use the same Release title (including v) to create a tag

4. Review and possibly amend release notes generated by clicking on the appropriate button

5. Enable Set as a pre-release and click on Publish release

6. Trigger client libraries update by opening update-specs-and-client-libraries and clicking over the Run workflow button

7. Select the type of change:

   Type	Description
   No change	no change expected to client library code
   Patch	bug fix not causing any change to client library interface
   Minor	backward compatible change to client library interface (e.g. new endpoint, new optional parameters)
   Major	non-backward compatible change to client library interface (e.g. remove or change endpoint, new mandatory parameters)

8. Select the language(s) for which client library(-ies) should be refreshed

9. Press Run workflow, a new PR will be created for each library or overridden if already present (steps 6-9 might be repeated)

10. For one client library at the time, check if workflows are green or update tests as needed (they can't run in parallel)

11. Reference any additional change in auto-generated PR's description, merge the PR and wait for each workflow completion

12. Draft a new client library release, by first clicking on the Releases button and Draft a new release afterwards

13. Use the release field's value from .release.json file as Release title, including the v prefix

14. Create a tag with same value as the Release title and click on the Generate release notes button

15. Copy and paste release notes What's changed section from onfido-openapi-spec's release notes just below the Refresh onfido-... line, by:

    1. Removing lines that doesn't apply to current library and reference to current language if present
    2. Indenting of two spaces each line and replacing the intial asterix (*) with dash (-)
    3. Removing by... (till the end of the line) for keeping CHANGELOG.md file clean

16. Any additional change manually performed in the library (e.g. updated tests, etc) needs to be added before the Refresh onfido-... line, indented as usual (but using - as a list marker to make line appearing in the CHANGELOG.md file).

17. Click on Publish release button

18. Check that workflows have been succesfully executed (by clicking on the Action button)

19. Replace Refresh onfido-... line in Release notes with the more appropriate Release based on... line from CHANGELOG.md file

20. Repeat steps 12-19 for each client library to deliver

21. Open onfido-openapi-spec release created a few steps before, untick Set as a pre-release, tick Set as the latest release and click on the Update release button to save it

22. If client library is targetting a new API version, update the documentation with new client libraries version