Skip to content

Latest commit

 

History

History
72 lines (53 loc) · 5.49 KB

CONTRIBUTING.md

File metadata and controls

72 lines (53 loc) · 5.49 KB

Contributing to Fingerprint Pro Server API OpenAPI

The repository contains OpenAPI definition files for various Fingerprint Pro Server-side APIs.

Schemas

You can find the schemas definitions in the schemas folder. You can find information about OpenAPI 3.0.3 in the official specification.

Contributing to the schema definition

  • 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 the examples folder.

Previewing changes

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.

  1. Clone this repository: git clone https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi.git
  2. Install dependencies: pnpm install
  3. Run pnpm dev to start the demo app

Code of demo application is in src folder.

Linting the schema

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

Schema Validation

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

Describing changes

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

Legend

  • 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 package
  • minor - version of the change, can be: patch, minor, major

Publishing changes

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