The repository contains OpenAPI definition files for various Fingerprint Pro Server-side APIs.
You can find the schemas definitions in the schemas folder. You can find information about OpenAPI 3.0.3 in the official specification.
- If you are not familiar with the OpenAPI format, you can watch this video summary (1.5x speed recommended).
- Authoring schemas is easier with IDE support. For VS Code, you can use OpenAPI (Swagger) Editor. You can look for similar extensions for your IDE of choice.
- OpenAPI schema is repetitive, the easiest way to add something (schema, endpoint, response, property...) is to copy-paste an existing entity and modify it. Try to follow the established patterns for naming, ordering, example values, example files, etc.
- You can reference the OpenAPI specification for more information.
- If you are adding a new signal, please also add it to
get_event_200.json
,webhook.json
,get_event_200_all_errors.json
and other relevant files in theexamples
folder.
Use the included Swagger UI demo app to dynamically render your changes into a documentation site a preview them there. Some mistakes and inconsistencies are much easier to spot in rendered documentation than by looking at the raw schema.
- Clone this repository:
git clone https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi.git
- Install dependencies:
pnpm install
- Run
pnpm dev
to start the demo app
Code of demo application is in src folder.
- Your IDE (with the right extensions/plugins) should warn you if your schema does not follow the OpenAPI specification.
- You can also run
pnpm run lintSchema
to run your schema through a linter. - This check also runs in the CI pipeline for your PR.
The schema is currently created separately from the API code. This is a bad practice, but we will fix it in future API versions. To validate that schema matches the actual API implementation we use a special validation script.
- It validates the schema against JSON examples file from examples folder. Note that some files in the examples folder appear unused like
get_event_extra_fields.json
, but they are downloaded and used for validation by individual SDK repositories. - It also generates fresh identification events using the TEST_SUBSCRIPTION env variable, retrieves fresh Server API responses and validates the schema against those.
- You can run
pnpm run validateSchema
to validate the schema locally.- You can create a
.env
file according to.env.example
and set the TEST_SUBSCRIPTIONS variable to include your personal Fingerprint subscription. - Or you can ask the DX team to provide you with the same test subscriptions as are used in the CI pipeline.
- You can create a
- This check also runs in the CI pipeline for your PR and once a day as a scheduled job.
- If you are adding things to the schema, you can also try adding the appropriate validations for the changes to the
validateSchema.ts
script. If you run into problems, the repository maintainers will be happy to help or to add the validations themselves as part of the PR review.
Releases from this repository are propagated to our server-side SDKs, that's why it's important to provide meaningful release notes if there are relevant changes. We use changesets for that. If you want to describe your changes, run:
pnpm run changeset
and follow steps in the CLI. It will create a new markdown file in .changeset
folder, don't forget to commit it with your changes.
Example changeset looks like this:
---
'fingerprint-pro-server-api-openapi': minor
---
**visitors**: Add the confidence field to the VPN Detection Smart Signal
visitors
- scope of the changes. Scopes are defined in the config/scopes.yaml file. Certain scopes are ignored in certain SDKs if they are not supported, meaning that they will be ignored for them. You will be prompted to select scope in the CLI.Add the confidence field to the VPN Detection Smart Signal
- meaningful description of the change.fingerprint-pro-server-api-openapi
- name of the packageminor
- version of the change, can be:patch
,minor
,major
- On merge into
main
, if there are relevant changes, the Release workflow can be triggered, which will consume created changeset files and create PR with bumped version and updated changelog. - When a PR is merged into
main
, the latest schema is automatically published to the GitHub pages. - The changes are currently NOT automatically published to the Documentation API Reference repository. You need to publish them manually using Readme CLI or Readme dashboard. The DX team is happy to assist.