Skip to content

Laying a foundation

Jump to bottom
Justin "J.R." Hill edited this page Dec 20, 2023 · 1 revision

Laying a foundation

After adding a new SDK, some light work may be required for correctness and functionality.

Adjusting defaults

Some of the defaults from OpenAPI generator may not make sense for OpenFGA, or they may be inconsistent with options used by other OpenFGA SDKs. Take time to review the options for the generator for your language and the options it provides.

Some configurations can impact all usage of the SDK, like whether to use the asynchronous features of a language. Other configurations may not affect the code at all, but be critical in other ways, like links in project metadata to the OpenFGA project website.

Find the documentation for your generator and its configuration. Make adjustments or additions as needed to the OpenAPI Generator inputs found in config/clients/<LANG>/config.overrides.json.

Where possible, consider replacing mustache references to these overrides with common overrides found in config/common/config.base.json.

Testing basic functionality

At this point the SDK should have a low-level client with a name similar to OpenFgaApi. It should be possible to use that to perform HTTP requests against a testing OpenFGA server running unprotected locally on the same machine.

  1. With Docker installed, run a basic local server with the command:
docker run -p 8080:8080 -p 3000:3000 openfga/openfga run

  1. The output from the docker command will have a message like: starting openfga playground on http://localhost:3000/playground

  2. Open this playground URL in your browser of choice.

  3. In the playground create a store with the button labeled NEW STORE

  4. After creating the store, use the button labeled SAVE to save the default authorization model.

  5. Use the ⋮ menu in the top right of the playground and copy both the "Store ID" and the "Authorization Model ID"

  6. Using your generated client, make calls to the local OpenFGA server from step 1 above. You can use OpenFGA's Getting Started guide for example calls you can make, and the output to expect.

  7. Make any necessary adjustments to the SDK for it to behave correctly.

Consider using this as an opportunity to contribute integration tests. The Java SDK and its test-integration-client-java Make target in the project's Makefile can be referenced for introducing an integration test.

Remove unnecessary files

Take this time to remove unnecessary files.

Especially if you were using the setup script, there will be unused files (and possibly unused directories of files) that are only used for alternative software choices like HTTP libaries, build and packaging tools, frameworks, test libraries, serialization/deserialization libraries, or other CI/CD services that will not be used in your SDK.

Remove the unnecessary mustache template files from the source code. If the file is still rendered when building the SDK, also add it to the config/clients/<LANG>/.openapi-generator-ignore file.

Clone this wiki locally