updated API spec #1697
Closed
updated API spec #1697
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
b5
added
API
using operationId & http verbs to draw an explicit mapping between lib methods and our HTTP api, with proposed changes to endpoints
|
I think it's easier to look at this as a table. Here's a first unfinished pass. @ramfox I'd love it if you could take over
|
|
Got it! Going to do a pass specifically on aligning/finishing out the current table. b5 and I spoke about an additional round of work that goes with this in parallel: documenting/examining the params of each endpoint |
|
Talked with @dustmop & he's agreed to take on an audit of params & param fields |
Notes
|
|
Table after our api spec discussion 03/19/2021
Notes
|
|
Latest API list SugarThe purpose of the API pacakge is to expose the lib.RPC api and add syntatic sugar for mapping RESTful HTTP requests to lib method calls
RPCThe purpose of the lib pacakge is to expose a uniform interface for interacting with a qri instance
"Protocol Endpoints"We're going to ignore this work until later, but eventually we'd like to group these under a "sync" noun:
ExamplesFrom the API pacakge it should be a one-liner to surface the RPC api from a package api
func (s *Server) Serve() error {
mux, _ := s.inst.GiveAPIServer()
AddGetHandlers(mux)
} |
|
need to do another pass & will either use this pr or cannibalize a tangential issue, but here is some tracking and unanswered questions around the api refactor |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Now that we have/soon will have a bunch of really big refactoring under our belts, I think we should be doing a massive overhaul of our API endpoint routing before cutting a release. This PR proposes a bunch of spec changes, while also aiming to explicitly document the connection between API endpoints & lib methods by way of the
operationIdfield in the open api spec.If we get this right & fill in the doc we'll leave with spec, accurate documentation, and punchiest for getting our API into release-ready shape.
Lots of work to do here to fill in possible responses & query params based on input param structs. I think we should start with a high-level audit of the proposed endpoint changes