The finAPI documentation is based on OpenAPI 3 format (often also refered to as Swagger). OpenAPI is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. A variety of tools is available to generate code, documentation and test cases given an OpenAPI interface file. You will find more information on the OpenAPI specification page.
One very useful feature of OpenAPI is the possibility to auto-generate SDKs based on our API-documentation. These SDKs facilitate the implementation of our API into your project and can greatly reduce the development time to integrate finAPI. Such generators usually produce good results, but it's likely that you have to fix or adjust the code to meet your special needs.
A generator we recommend is openapi-generator, but there are other generators available on the internet.
Migration from the swagger generator
Up to Access release v1.122.x, the API documentation was based on Swagger 2 format, and the previous version of this article recommended to generate a client from the https://editor.swagger.io page. The "Download SDK" button in our API documentation frontend refered to the same swagger generator.
We no longer recommend this generator as from our experience the openapi-generator (which is derived from the original Swagger generator) has a better quality. So beginning with Access v1.123.0, the "Download SDK" feature uses this new generator.
So if you have generated a SDK from editor.swagger.io in the past or by using the "Download SDK" feature of our API documentation prior to Access release v1.122.x, you may notice differences in the generated code you have to adapt to.
Here a few notes on generator changes for major languages:
- For "java", the structure of the generated code is mostly identical, just the code inside the generated methods has slightly changed. If you use the extended method variants with "Call" suffix (e.g. "getTokenCall", you need to adjust the two progress listener parameters, which are now combined into a single ApiCallback object. Also the default package name changed from "io.swagger.client" to "org.openapitools.client" and the library dependencies have been upgraded. You can override the generated package names by installing the new generator locally as described later.
- Also for "csharp", the structure of the generated code is identical, but the default namespace changed from "IO.Swagger.Api" to "Org.OpenAPITools.Api", and the source directory was renamed.
- For "python", the client has a new layout. By choosing "python-legacy" language, you get the same results as for "python" with the old generator.
- For "go", the code structure is basically identical, but for each service call a separate method call to prepare the parameters is now required, follow by a call to the "execute" method. Also the target package changed from "swagger" to "openapi".
Further details on generator changes can be found on the Migrating from Swagger Codegen page.
Of course you can still use the Swagger generator from editor.swagger.io (which also supports OpenAPI 3 format) to not have to adapt to the changes mentioned before. However, you may still run into minor client changes due to the migration from Swagger 2 to OpenAPI 3 format.
Download SDK from finAPI documentation site
The easiest way to generate a SDK is directly integrated into the finAPI documentation site:
Just open https://docs.finapi.io, select your desired API in the "SELECT PRODUCT" combobox and click on "Download SDK"
In the popup dialog, select the desired target language in the combobox. For some languages, different generators are available.
By clicking on "DOWNLOAD SDK", your request is forwarded to http://api.openapi-generator.tech, which is the online version of the openapi-generator mentioned above.
After a few seconds the download of a ZIP file containing the generated client will be triggered. Unpack the client and integrate it into your project.
Note: Usually a full project is generated including build files for the respective language, but as this kind of generation runs the generator with default options, the code may not fit all your needs. The "Install SDK generator locally" approach described below is more flexible.
Install SDK generator locally
As mentioned, the online variant operates with default generator settings. But the openapi-generator project defines many options to control the generator output, depending on the chosen target language. By installing the openapi-generator locally, you are able to use this options to get better results which may reduce the need of manual changes to the generated code.
Please refer to https://openapi-generator.tech/docs/installation, it describes different options for a local installation of the generator, choose the option that fits best for you.
As an example, we describe the NPM option. Please make sure you have NPM and a Java Runtime environment installed.
Install the generator
npm install @openapitools/openapi-generator-cli -g
Show available languages
npx @openapitools/openapi-generator-cli list
Run generator with default options
Example: "java" language
npx @openapitools/openapi-generator-cli generate -g java -i https://sandbox.finapi.io/api-docs/openapi-access-latest.yaml
Show custom generator options for the chosen language
Example: "java" language
npx @openapitools/openapi-generator-cli config-help -g java
Run generator with custom options
Example: "java" language, set apiPackage=io.finapi.client
npx @openapitools/openapi-generator-cli generate -g java -i https://sandbox.finapi.io/api-docs/openapi-access-latest.yaml -p apiPackage=io.finapi.client
By default, the local generator creates the client in the current directory, this can be overridden by the -o option.
If your client application cannot handle HTTP PATCH and/or DELETE methods, you have to adjust the generated SDK code by using finAPI's "HTTP Method Override" feature, which is explained here.