The apollo command is basically functional but so, so user unfriendly. It's user-hostile. Amti-user
It's not so much a problem right now because there's only one service on apollo and it barely works
This issue is a list of possible improvements that can be made.
Make it easy to get to my server's landing page
The Apollo server itself shows a rich html listing of what services are available, and provides the readme for each. We should make it easy to get the active server's help pages (local, staging or prod)
List available services
openfn apollo ls should list all the services, just like the apollo root soes
Show detailed docs for a service
openfn apollo help <service-name> should print detailed help, including usage examples, for a given endpoint.
The help data must come the apollo server. Does this mean we just dump the readme?
Generate sample data
Some services need sample data. Can the server provide one or more sample datasets and the CLI auto-download them? I'd like to run openfn apollo adator_gen with default values and get something back. I think? Is that even a nonsense use case?
Make API key management easier
Many services need API keys, and at the moment it's the wild west.
It would be nice to do:
openfn apollo add-key <model-name> <key>
And then whenever the CLI calls a service with that model, it can default api_key to that key.
I guess the key is saved, encrypted, in the CLI repo.
Read Env vars
In JSON payloads, we should be able to read stuff from env vars. Like any value of the form $API_KEY (all one word, all caps, start with dollar) we should try and resolve against process.env
We could also allow payloads to be a JS module that exports JSON, which gives better env management and even data generation capabilities.
Add utils or wrappers for template generation
Template generation is kinda hard.
I need to get an openAPI spec
Even worse, right now I need to download it to JSON and copy/paste it into my payload
I need to work out what endpoints are available and enter the right one
There is no integration to the monorepo so I can't easily raise a PR
Ideas:
allow the spec json object to take a URL. Either the CLI or the remote service should be able to map this to JSON
give me some openapi helper functions, like listing all the endpoints for a particular API. I don't think this is worth the effort to be fair
There's a difference betwee generating adaptor.js and generating an adaptor. There's an extra chunk of logic in the CLI that needs to generate an adaptor template in the monorepo, generate adaptor.js, and paste the generated adaptor in the right place. I have been thinking of this as a bespoke CLI command (openfn generate adaptor ?) but I am anxious about this generate namespace. What if the monorepo's generate command called out to openfn apollo as part if its generation pipeline? So it's a monorepo task and not a CLI task?
Public Documentation
We should host user-friendly API documentation somewhere, I guess on docs.openfn.org. Probably with tutorials. Neither the CLI nor the server is mature enough for this yet.
The
apollocommand is basically functional but so, so user unfriendly. It's user-hostile. Amti-userIt's not so much a problem right now because there's only one service on apollo and it barely works
This issue is a list of possible improvements that can be made.
Make it easy to get to my server's landing page
The Apollo server itself shows a rich html listing of what services are available, and provides the readme for each. We should make it easy to get the active server's help pages (local, staging or prod)
List available services
openfn apollo lsshould list all the services, just like the apollo root soesShow detailed docs for a service
openfn apollo help <service-name>should print detailed help, including usage examples, for a given endpoint.The help data must come the apollo server. Does this mean we just dump the readme?
Generate sample data
Some services need sample data. Can the server provide one or more sample datasets and the CLI auto-download them? I'd like to run
openfn apollo adator_genwith default values and get something back. I think? Is that even a nonsense use case?Make API key management easier
Many services need API keys, and at the moment it's the wild west.
It would be nice to do:
And then whenever the CLI calls a service with that model, it can default
api_keyto that key.I guess the key is saved, encrypted, in the CLI repo.
Read Env vars
In JSON payloads, we should be able to read stuff from env vars. Like any value of the form
$API_KEY(all one word, all caps, start with dollar) we should try and resolve against process.envWe could also allow payloads to be a JS module that exports JSON, which gives better env management and even data generation capabilities.
Add utils or wrappers for template generation
Template generation is kinda hard.
Ideas:
openfn generate adaptor?) but I am anxious about this generate namespace. What if the monorepo's generate command called out toopenfn apolloas part if its generation pipeline? So it's a monorepo task and not a CLI task?Public Documentation
We should host user-friendly API documentation somewhere, I guess on docs.openfn.org. Probably with tutorials. Neither the CLI nor the server is mature enough for this yet.