Support discovering OpenAPI document from Link header?
#2128
Comments
|
I think more generically See #1511 #724 #734 for previous discussions including |
|
Any chance that this usage pattern could be documented better? A search for If it's useful, I can try to figure out where to add appropriate documentation? |
|
When #110 (@darrelmiller) is resolved we would definitely look at an updated version of #734 wording, either in the spec. or in a guidance / technical note document. |
|
+1 to using |
|
I recall @darrelmiller had some objection to using a
Of course one issue it doesn't cater for is an organisation having many APIs (which could be handled by something like apis.json). There is also the schema.org WebAPI type in this discovery space. |
|
I think using |
|
This is the |
|
Sorry, I think I've misunderstood this issue. I think having link pointing to documentation of current method is good idea, my comment does not really applies to this discussion. (I was thinking of service discovery, i.e. getting Open API json just from domain). |
|
Why be specific about the Link header and not just recommend the pattern by recommending a link relation to use? |
While doing parallel work to implement an API, the Gin framework proved especially challenging to integrate with other HTTP handlers (e.g. GRPC or the GRPC Gateway). It was difficult to convert between the HTTP Handler interface and Gin's "context" approach, and Gin replaced the way status codes were delivered (breaking compat between the two). On review, Gin was becoming more of a challenge to work with than the value it brought. Rather than "opt in" to the entire Gin framework, this commit replaces Gin with a simpler, closer to the standard library framework — "Chi". This seems to be well maintained, in fairly broad use and easier to reason through. === Additional Tests In the initial, gin design there were fewer tests. This commit adds more test, somehow achieving 100% in the server package. === Errors w. Context One of the things the Gin package did that was nice was centralize error handling for the API, through the use of "context errors". This commit replicates a simpler version of the same, allowing requests to end by setting context on the request. There is a new, central middleware that will look at all requests egressing the stack, and if there is an error, write out an appropriate response. This prevents many painful repetitions of the same content. === Problem+JSON With the use of the Errors library, the opportunity came up to improve the way erros are displayed. One of the more useful ways — absent a UI — is to respond with a JSON (or similarly structured) blob. This commit takes advantage of an existing library that does exactly this, rather than writing it again. === Noroute to Get<slug> This commit swaps the existing "noroute" design to a design that matches the first slug in the URL. This is marginally different than the previous design, which would (by definition) match the entire URL. This allows, in principle, other bindings later for things like the .well-known URLs: * OAI/OpenAPI-Specification#2128
While doing parallel work to implement an API, the Gin framework proved especially challenging to integrate with other HTTP handlers (e.g. GRPC or the GRPC Gateway). It was difficult to convert between the HTTP Handler interface and Gin's "context" approach, and Gin replaced the way status codes were delivered (breaking compat between the two). On review, Gin was becoming more of a challenge to work with than the value it brought. Rather than "opt in" to the entire Gin framework, this commit replaces Gin with a simpler, closer to the standard library framework — "Chi". This seems to be well maintained, in fairly broad use and easier to reason through. === Additional Tests In the initial, gin design there were fewer tests. This commit adds more test, somehow achieving 100% in the server package. === Errors w. Context One of the things the Gin package did that was nice was centralize error handling for the API, through the use of "context errors". This commit replicates a simpler version of the same, allowing requests to end by setting context on the request. There is a new, central middleware that will look at all requests egressing the stack, and if there is an error, write out an appropriate response. This prevents many painful repetitions of the same content. === Problem+JSON With the use of the Errors library, the opportunity came up to improve the way erros are displayed. One of the more useful ways — absent a UI — is to respond with a JSON (or similarly structured) blob. This commit takes advantage of an existing library that does exactly this, rather than writing it again. === Noroute to Get<slug> This commit swaps the existing "noroute" design to a design that matches the first slug in the URL. This is marginally different than the previous design, which would (by definition) match the entire URL. This allows, in principle, other bindings later for things like the .well-known URLs: * OAI/OpenAPI-Specification#2128
While doing parallel work to implement an API, the Gin framework proved especially challenging to integrate with other HTTP handlers (e.g. GRPC or the GRPC Gateway). It was difficult to convert between the HTTP Handler interface and Gin's "context" approach, and Gin replaced the way status codes were delivered (breaking compat between the two). On review, Gin was becoming more of a challenge to work with than the value it brought. Rather than "opt in" to the entire Gin framework, this commit replaces Gin with a simpler, closer to the standard library framework — "Chi". This seems to be well maintained, in fairly broad use and easier to reason through. === Additional Tests In the initial, gin design there were fewer tests. This commit adds more test, somehow achieving 100% in the server package. === Errors w. Context One of the things the Gin package did that was nice was centralize error handling for the API, through the use of "context errors". This commit replicates a simpler version of the same, allowing requests to end by setting context on the request. There is a new, central middleware that will look at all requests egressing the stack, and if there is an error, write out an appropriate response. This prevents many painful repetitions of the same content. === Problem+JSON With the use of the Errors library, the opportunity came up to improve the way erros are displayed. One of the more useful ways — absent a UI — is to respond with a JSON (or similarly structured) blob. This commit takes advantage of an existing library that does exactly this, rather than writing it again. === Noroute to Get<slug> This commit swaps the existing "noroute" design to a design that matches the first slug in the URL. This is marginally different than the previous design, which would (by definition) match the entire URL. This allows, in principle, other bindings later for things like the .well-known URLs: * OAI/OpenAPI-Specification#2128
|
If anyone comes around wandering about this, I did it like that: For json it would be |
I'm looking at various options to "upgrade" a simple API (HTTP POST of CloudEvents) to allow clients and servers to be able to extend into more complex OpenAPI space (e.g. "what events are you interested in" or "what types of events might be returned in the HTTP response").
One attractive option would be to provide a
Linkheader pointing to the OpenAPI spec on the existing endpoint to provide a hint that upgrade is available.I don't see a documented
rel(relation) value for OpenAPI; would something like "oas-3.0" be a reasonable value?The text was updated successfully, but these errors were encountered: