Skip to content

How To update edu sharing OpenAPI Client

Jump to bottom
criamos edited this page Aug 30, 2024 · 1 revision

How-To: Update the edu-sharing API Client

You might have noticed that there is a edu_sharing_openapi/-directory within the project root of oeh-search-etl: This directory was (automatically) generated via openapi-generator-cli according to the current OpenAPI Specs (v3) of the edu-sharing repository software.

Bookmarks

Prerequisites

Before getting started:

  • Please make sure that you have installed the openapi-generator-cli toolkit
  • (The described steps in this guide were tested with Ubuntu 22.04 LTS)

The following commands will be using the Docker method of generating the API Client because this method generally requires less set-up steps compared to a local installation of openapi-generator-cli.

Locate your openapi.json

First, you need to locate openapi.json-file that Swagger automatically generates:

  • If you open the edu-sharing REST API (Swagger interface) in your browser, e.g. https://stable.demo.edu-sharing.net/edu-sharing/swagger/ you should see a link to it in the top left corner of the interface
  • You might also try https://<URI_of_your_edu-sharing_repository>/edu-sharing/rest/openapi.json

In this example the openapi.json-file is located at https://stable.demo.edu-sharing.net/edu-sharing/rest/openapi.json

User Credentials need to be base64 encoded!

If your edu-sharing repository requires a username and password to access the openapi.json-file, these login credentials will also be necessary in the next step.

Let's assume your username is hello and your password is world: The openapi-generator-cli toolkit expects these credentials to be base64 encoded as username:password. In our example hello:world would look like this: aGVsbG86d29ybGQ=

CLI Step-by-Step: Generating the API Client

With your terminal / console of choice: navigate to the project root directory of oeh-search-etl

The following command uses the Python Generator of openapi-generator-cli with the above-mentioned (example) login credentials:

docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate -i https://stable.demo.edu-sharing.net/edu-sharing/rest/openapi.json -a 'Authorization: Basic aGVsbG86d29ybGQ=' -g python -o /local/edu_sharing_openapi --package-name edu_sharing_client

Attention: Please take a good look at the -a (shorthand for --auth) parameter! Even though the OpenAPI Generator Documentation for the "generate"-command describes this parameter as requiring a URL-encoded string, only a base64-encoded string would actually work as expected (as of 2024-08)!

This (unexpected) behavior of openapi-generator-cli might change in the future.

Optional: Taking over ownership of the directory

If the API Client was successfully generated, you should now see a edu_sharing_openapi/-directory in the project root. Depending on your Docker installation, the generated folder might be locked / owned by the root-user, which means you need to take ownership of this directory (and recursively all its subdirectories) first:

To acquire ownership rights for the current user:

sudo chown -R $USER edu_sharing_openapi/

PyCharm Users: Mark the directory as "source root"

The newly generated API Client will be located within the edu_sharing_openapi/edu_sharing_client/ directory.

If you are using the PyCharm IDE, you will have to mark the edu_sharing_openapi/-directory as a "source root"-folder for code auto-completion and insights, otherwise imports will fail.

To do this, right-click the edu_sharing_openapi/-director, select Mark directory as -> Sources root.

(For further details, please consult: PyCharm Docs - Configuring Project Structure)

Carry over dependencies from the (second) pyproject.toml file to the main pyproject.toml

You should now see a (second) pyproject.toml-file in the newly created edu_sharing_openapi/-directory:

oeh-search-etl/
├── converter/
│   └── spiders/
│       └── ...
├── ...
├── edu_sharing_openapi/
│   ├── edu_sharing_client/
│   │   └── ...
│   └── pyproject.toml  # (generated by openapi-generator-cli)
└── pyproject.toml  # (project dependencies are defined here)

The edu_sharing_openapi/pyproject.toml lists all dependencies that are necessary to use the API client (by itself). Since the API Client is heavily used in es_connector.py, the dependencies need to be available in the main pyproject.toml as well. Dependencies that are not already listed in the main pyproject.toml can (manually) be copied over from edu_sharing_openapi/pyproject.toml by using Poetry's Dependency Groups feature:

# pyproject.toml

[tool.poetry.group.edu_sharing_client.dependencies]
pydantic = ">=2.8.2"
typing-extensions = ">=4.12.2"

(This will ensure that during future set-ups of your development environment, poetry install will cover the main project dependences as well as the necessary dependencies for the edu-sharing API Client.)

That's it!

You should now be able to use the edu-sharing API client within the es_connector.py and (if the need arises) update the client on your own.

Thank you for your attention!

Addendum

For historic context: the (outdated) "swagger"-API-Client generation

The original edu-sharing API client (edu_sharing_client/) was generated with the predecessor of openapi-generator-cli, which was called swagger-codegen-cli. It required a specific version of the swagger-codegen-cli and Java / Maven to be set up on the dev's machine.

(see: Swagger Codegen Documentation and "What is the difference between Swagger Codegen and OpenAPI Generator?")

For historic context's sake, this command was used to generate the (old) API client:

# creating the swagger client: 
java -jar swagger-codegen-cli-3.0.20.jar generate -l python -i http://localhost:8080/edu-sharing/rest/swagger.json -o edu_sharing_swagger -c edu-sharing-swagger.config.json
Clone this wiki locally