Skip to content

Adding a new SDK

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

Adding a new SDK

Using the setup script

There is a helpful script to setup a new SDK

make setup-new-sdk
  1. It will ask you for a an SDK ID, use something like: go, js, dotnet, java, etc...
  2. It will ask you for a valid generator
  3. Then in will initialize all the files, you will need to add the configuration specific to that sdk
  4. Now you can run make build-client-${SDK_ID} to generate the SDK

Manually

  1. Create config dir in: config/clients/{lang}/. It should include:
    • CHANGELOG.md: To be updated as new releases are generated
    • generator.txt: the name of the generator to use. Must be a valid generator
    • config.overrides.json: Custom config for this generator + overrides to the common config in config/common/config.base.json
    • .openapi-generator-ignore: Any files that the generator should ignore and not built
    • template-source: Newer SDKs should have this to mark what commit of the generator we branched off
    • template/ directory
      • LICENSE: Apache-2.0 License
      • .github/workflows/main.yml: Any CI checks that need to run
      • The following files, each with the relevant section (look at the JS template for an example):
        • README_installation.mustache
        • README_initializing.mustache
        • README_calling_api.mustache
        • README_api_endpoints.mustache
        • README_models.mustache
        • README_license_disclaimer.mustache
        • README_custom_badges.mustache (optional, any custom badges for this specific SDK)
        • gitignore_custom.mustache (optional, any custom ignores for this specific SDK)
        • NOTICE_details.mustache (optional, see Updating the Notice files)
      • custom files according to the generator
  2. Update the Makefile.
    1. add a target for the new sdk
.PHONY: build-client-{{LANG}}
build-client-{{LANG}}:
	make build-client sdk_language={{LANG}} tmpdir=${TMP_DIR}
	# ... any other custom build steps ...
  1. add it as a dependency to the build-all-clients 
.PHONY: build-all-clients
build-all-clients: build-client-js build-client-go ...  build-client-{{LANG}}
  1. add a target for the new sdk's tests that depend on the build target
.PHONY: test-client-{{LANG}}
test-client-{{LANG}}: build-client-{{LANG}}
	# ... any custom test code ...
  1. add it as a dependency to the test-all-clients 
.PHONY: test-all-clients
test-all-clients: test-client-js test-client-go ...  test-client-{{LANG}}

Note: Try to ensure that the SDK is built through container files so that other contributors would not need to set up the full language framework/toolchain whenever they need to contribute. Checkout the go sdk build steps as an example.

Updating the Notice files

1- Ensure that fossaComplianceNoticeId has been set in each SDK's config overrides. 2- Run make update-fossa-reports

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