SDK roadmap proposal

[nitrosx]

Following up to the discussion regarding the SDK auto generation that took place on the SciCat Collaborator meeting held on 2024/08/20.
Considering all the input and feedback provided by the participants, I proposed the following roadmap:

• Finalize auto generation of javascript and python SDKs CI/CD
• Publish them automatically on the language specific platforms automatically with the following names:
  • typescript angular: scicat-sdk-ts https://www.npmjs.com/package/@scicatproject/scicat-sdk-ts
  • python: scicat_sdk_py https://pypi.org/project/scicat-sdk-py/
  • python with pydantic data model: scicat_sdk_pydantic https://pypi.org/project/scicat-sdk-pydantic/
• Publishing platforms are:
  • javascript: npm-js
  • python: pypi
• Documentation. Clearly state that SDKs are provided as they are. No testing is done during CI/CD
• Refactor FE to use new SDK:
• Include new languages as needed
  • typescript node: scicat-sdk-ts-node
  • Golang
• Assess current pySciCat version.
• Establish the effort to build pySciCat on top of scicat-sdk-py and add extensive testing.
• Offer pySciCat as the low level SciCat python library, providing the following extras on top of the SDKs:
  • additional functionalities not included in the SDK,
  • extensive testing
  • backward compatibility with current versions
  • different release cycle from the SDK due to human revisions
• After 6/12 months evaluate if having scicat-sdk-py(dantic) and pyScicat is sustainable and the most sensible solution.
  We will adapt the road map forward based on the outcome.

[rkweehinzmann]

as mentioned in the meeting yesterday I assume you meant: scicat-sdk-ts for typescript not javascript.

[minottic]

this is the idea I vaguely mentioned in the meeting:

1. take the scicat-be-next tests. For example this test. Most of the tests are written as HTTP calls
2. we refactor this block and the others, to take from a config file the route /api/v3/Datasets/isValid, the method post, the payload TestData.DerivedCorrect and the expected result TestData.EntryValidStatusCode and property("valid").and.equal(true); (and everything else, e.g. the queryParams or headers or pathParameters). Note that some values already come from dedicated files.
3. we assess the feasibility of this refactoring for all tests and, if positive, do it for all.
4. whenever we add a new endpoint (or piece of code which needs testing) we write the test in js to the appropriate file and follow the schema defined in 2. So, for example, if we add the derivedDataset GET datasetsByOwner/{ownerId}, we add a test in test/DerivedDataset.js which takes the configuration from e.g. derivedDatasets.yaml which is in this format:

route: /api/v3/datasets/datasetsByOwner
pathParameters: 
 id: 123
authenticated: yes
expected: 
 length: 2
 content: [owerGroup: 123, ownerGroup: 123]

5. when we generate the SDKs, we can take the route and all its parameters from the yaml file (e.g. the /api/v3/datasets from derivedDatasets.yaml) and with the openAPI.json we map the test route to the generated SDK (we would need to check if, when generating the e.g. python SDK, there is a mapping anywhere of the python code to the original openAPI.json. For example, if there is anywhere a map like GET datasetsByOwner/{ownerId} -> scicat.getDatasetsByOwner.setOwner(ownerId)).
6. for each SDK language, we write a dynamic tests generator that uses the openAPI.json to SDK map and the tests config yaml files. This generator should output an HTTP call for every route in the tests yaml files and test the expected results from the yaml files using the inputs contained in the same yaml file (e.g. the GET datasetsByOwner/{ownerId} in python should test if calling scicat.getDatasetsByOwner.setOwner(123) returns a list of length 2 with [owerGroup: 123, ownerGroup: 123])

Just food for thoughts, I realise it sounds there's a lot of work in terms of investigation and implementation...

[nitrosx]

@minottic interesting idea, and a good one for the long term.
Short term, I am afraid it might be to much effort.

Maybe we could start working on your idea in parallel with providing SDKs as-they-are with no testing.

[nitrosx]

@dylanmcreynolds what are your thoughts on my proposal?

[dylanmcreynolds]

Related issues:
#1251
SciCatProject/pyscicat#59

[yusufhalabi]

@nitrosx @dylanmcreynolds @minottic Hey, at Fern (buildwithfern.com) we generate idiomatic SDKs in a bunch of languages. Would love to help you guys out in generating Typescript + Python SDKs. Interested in chatting / a demo?

[nitrosx]

Updated main description with current status.