boavizta / boaviztapi-sdk-rust Goto Github PK

View Code? Open in Web Editor NEW

3.0 2.0 0.0 167 KB

✳ Rust client library for Boaviztapi.

License: GNU Affero General Public License v3.0

Rust 99.53% Shell 0.47%

boaviztapi-sdk-rust's Introduction

boaviztapi-sdk-rust

Rust client library for Boaviztapi.

Versions supported

SDK version 1.2.0 supports Boavizta API 1.2.0
SDK version 1.1.0 supports Boavizta API 1.1.0
SDK version 1.0.1 supports Boavizta API 1.0.1 (and historical 0.3.x series)
SDK version 0.3.X supports Boavizta API of the 0.3.x series
SDK version 0.2.x support Boavizta API of the 0.2.x series (Neither SDK nor API will not be updated after release of Boavizta API v0.3.x - around June 2023)

Documentation

SDK documentation (crate) boavizta_api_sdk - Rust
Boavizta API documentation

How to generate the sdk for the latest version of BoaviztaAPI

SDK is generated from the published openAPI specification of Boaviztapi (http://api.boavizta.org/openapi.json).

We use openapi-generator-cli to generate the SDK. See GitHub - OpenAPITools/openapi-generator-cli: A node package wrapper for https://github.com/OpenAPITools/openapi-generator .

# Generate for public API
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate -i http://api.boavizta.org/openapi.json   -g rust  -o /local/ --package-name boavizta_api_sdk
# Local API (dev, using network host /!\)
docker run --network=host --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate -i http://localhost:5000/openapi.json  -g rust  -o /local/ --package-name boavizta_api_sdk

The generated code require some manual updates before being usable.

How to generate SDK for a specific version of API

To generate the SDK for a specific version of BoaviztaAPI (e.g. a dev branch or unreleased version), you have to:

retrieve the openapi.yml specification of the API
run the generator against this file
if needed publish the generated SDK wth an alpha version

Update the Cargo.toml before publishing the SDK

Metadata of Cargo.toml are overwritten by generation.

verify that version of package is consistent
update it with the following values

description = "A Rust client/sdk to access Boavizta API"
homepage = "https://boavizta.org"
repository = "https://github.com/Boavizta/boaviztapi-sdk-rust/"
readme = "README.md"
authors = ["boavizta.org", "olivier de Meringo"]
edition = "2018"
license-file = "LICENSE"

Ensure that the dependency on reqwest does not use native SSL(the default feature), but uses rust-tls . It makes cross compiling so much easier.

[dependencies.reqwest]
version = "^0.11"
default-features = false 
features = ["json", "multipart", "rustls-tls"]

How to publish the SDK

This is a manual action and should be done only by the maintainer of the SDK.

cargo login
cargo publish --dry-run
cargo publish

boaviztapi-sdk-rust's People

Contributors

Stargazers

Watchers

boaviztapi-sdk-rust's Issues

Investigate using progenitor to generate the SDK

Current SDK is difficult to generate for API V0.2x and likely future V0.3.x (see #6 )

Describe the solution you'd like

Test if generating the sdk with progenitor could ease life (avoid manual fixes on the generated code).

https://github.com/oxidecomputer/progenitor

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context

Using a different generator is a breaking change, it will imply to update the code using it (like cloud-scanner).

Automate publishing the SDK

Is your feature request related to a problem? Please describe.
Automate publishing the SDK when when a version is published in git

Describe the solution you'd like
Not sure yet

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Import existing Rust SDK

Import existing Rust SDK (initially maintained in cloud-scanner project)

import SDK code here as it is
publish the crate manually
- Identify requiered metadata for publication
- test publish on crate staging environment
- publish to crate.io
automate if time permit

See also https://www.printlnhello.world/blog/publishing-to-crates-io/#then-do-it-again-on-staging. It describes how to test publication on crate.io staging environment first.

And https://codeandbitters.com/published-crate-analysis/ for best practices around publishing crate and link to the source code.

Update SDK for API v0.3.x

Is your feature request related to a problem? Please describe.

Boavizta API v0.3.X may introduce some breaking changes that will affect SDK signatures.

Describe the solution you'd like

Publish a alpha version of the SDK for API V0.3.x

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context

branch v0.3 : https://github.com/Boavizta/boaviztapi/tree/v0.3
demo on : http://dev.api.boavizta.org/

It may also be a good time to switch the sdk generation mechanism #7

Update SDK to latest API v1.0.1

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Update SDK for API v1.0.2

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Openapi-generator fails to produce sdk code for API V0.2

Describe the bug

When attempting to generate the SDK for API V0.2.0 alpha, generated code does not consider the oneOf or anyOf properties (for example in the time_workload of cloud usage in https://dev.api.boavizta.org/docs#/cloud/instance_cloud_impact_v1_cloud_aws_post)

Known bug in open-api generator:

OpenAPITools/openapi-generator#9497

Maybe we could try a alternative sdk generator:

https://github.com/oxidecomputer/progenitor
initially mentionned in this threadq OpenAPITools/openapi-generator#7868 and zerotier/zeronsd#186

To Reproduce
Steps to reproduce the behavior:

Go to '...'
Click on '....'
Scroll down to '....'
See error

Expected behavior
Generate an enum with the different variants of time_workload (a f32 or a list of workload_time structs) instead of an empty struct.

Additional context
Add any other context about the problem here.

Update SDK for boaviztapi v2.x

Is your feature request related to a problem? Please describe.
Provide a SDK version adpated for Boaviztapi 2.x (including consumption profiles)

Describe the solution you'd like
Boaviztapi 2.X is not officialy released yet, so this sdk should be published as an alpha release.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

boavizta / boaviztapi-sdk-rust Goto Github PK

boaviztapi-sdk-rust's Introduction

boaviztapi-sdk-rust

Versions supported

Documentation

How to generate the sdk for the latest version of BoaviztaAPI

How to generate SDK for a specific version of API

Update the Cargo.toml before publishing the SDK

How to publish the SDK

boaviztapi-sdk-rust's People

Contributors

Stargazers

Watchers

boaviztapi-sdk-rust's Issues

Recommend Projects

Recommend Topics

Recommend Org