Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
137 lines (92 loc) · 8.71 KB

CONTRIBUTING.md

File metadata and controls

137 lines (92 loc) · 8.71 KB
Raw

Contributing to Fingerprint Server API OpenAPI

The repository contains OpenAPI definition files for various Fingerprint 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.

Comparing local schemas with published schemas

This repository includes a schema diff script used by CI to post a sticky PR comment with schema changes vs currently published GitHub Pages schemas.

Run it locally:

  1. Install dependencies: pnpm install
  2. Build local schemas: pnpm build
  3. Compare local build output (dist/schemas) with published schemas: pnpm schema:diff:published

Optional:

  • Save a JSON report: pnpm schema:diff:published -- --json-out ./tmp/schema-diff-report.json
  • Save the rendered PR comment body: pnpm schema:diff:published -- --comment-out ./tmp/schema-diff-comment.md
  • Compare against a custom published base URL: pnpm schema:diff:published -- --base-url https://fingerprintjs.github.io/fingerprint-pro-server-api-openapi/schemas

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

Choosing the version bump

A changeset is only needed when a change affects the generated SDKs. Pick the version bump as follows:

  • major - a breaking change: removing a field, schema, endpoint, or query parameter, narrowing a type, or making an optional field required. Very rare, and usually an accidental change to revert.
  • minor - a backwards-compatible addition: new fields, schemas, query parameters, paths, or methods.
  • patch - a backwards-compatible change that isn't an addition, e.g. deprecating a field, or a vendor extension that affects SDK code generation (like x-parameter-alias / x-aliased-parameter-name).

Don't create a changeset for documentation-only changes (descriptions, examples) or for vendor extensions that don't affect the generated SDKs.

Publishing changes

On every push into main (merged PR):

  • The built schema is published to GitHub pages.
  • The built schema is published as a raw yaml file.
  • After GitHub Pages deploy, the docs repo OpenAPI sync workflows run. They open a PR only if the published spec changed, which updates the API Reference.

See the publish.yml workflow for more details.

GitHub releases

GitHub releases are used to generate Server SDKs based on a specific version of the OpenAPI schema.

After merging to main, if there are relevant changes, you can manually trigger the Release workflow, which will consume created changeset files and create PR with bumped version and updated changelog.

Release note sync with SDKs

There are server-side SDKs (Node.js, Go, etc.) that consume the schema automatically. The file .changeset/changesets.zip is used during this process. It is not a build artifact, and it is not safe to delete by hand.

changeset version deletes the markdown files once it has folded them into the changelog, but the SDK repositories still need the originals to generate their own changelogs when they sync to a new schema version. So scripts/zipChangesets.ts archives them into .changeset/changesets.zip just before they are consumed, and that zip is committed as part of the release PR.

Lifecycle:

  1. pnpm changeset-version (run by the changesets release action) zips the pending changesets, then changeset version consumes the markdown files. The zip lands in the release PR.
  2. On release publish, .github/workflows/upload-changesets.yml runs scripts/uploadChangesets.cjs, which uploads the zip as the changesets.zip release asset that the SDK sync jobs download.
  3. The same workflow then opens a follow-up PR that removes the zip from main.

Step 3 only runs once the upload in step 2 has succeeded, so a zip that is still on main holds changesets the SDKs never received. zipChangesets.ts folds those into the next archive instead of overwriting them, so a failed release delays delivery rather than losing it.