Examples; replace Uber with USPTO #1419
Conversation
There was a problem hiding this comment.
I totally dig this direction and am happy even to approve it as-is (note: I didn't run it through any validators, but assume that was done already). Nice work!
There is a fine balance to strike between a simple, approachable spec and one that is too complicated. However, it's worth considering whether any of the following can be added:
- A generic example response, like
5xx - Verbs other than
get, especially apostexample. Uber didn't have those when it was written, and it's possible that the USPTO doesn't either. If that's the case, maybe it is worth adding a more complicated example. - There are no examples of reusable components. Again, that may be an intentional choice, just worth considering.
examples/v3.0/uspto.yaml
Outdated
| @@ -0,0 +1,216 @@ | |||
| openapi: 3.0.0 | |||
| servers: | |||
| - url: 'https://developer.uspto.gov/ibd-api' | |||
There was a problem hiding this comment.
Is it worth turning the scheme into a variable with enums of http and https?
If not, what about adding a description to explain the two URLs?
There was a problem hiding this comment.
I must confess I hadn't thought of using server variables for anything except the host, port or path (where RFC6570 templates are normally used), but happy to go with that, or the description option.
There was a problem hiding this comment.
I don't have a strong pref, either will improve this slightly. Given that http/https should be somewhat common, it seems like that is self-evident as a variable.
examples/v3.0/uspto.yaml
Outdated
| url: 'https://developer.uspto.gov' | ||
| email: developer@uspto.gov | ||
| tags: | ||
| - name: bulkdata |
There was a problem hiding this comment.
Consider a description for the tag to show best practices.
MikeRalphson
force-pushed
the
v3-examples
branch
from
36751dc
to
29ea26d
Compare
|
I've replaced the Bulk Data Search API with the Data Set API, as this has a
|
There was a problem hiding this comment.
Nice work @MikeRalphson ! We should consider this for the first patch release.
|
Thanks for all your work on this @MikeRalphson ! |
This PR replaces the commercial, outdated and oAuth protected Uber example with a public, current and open one from the US Patent & Trademark Office.
Disclaimer: This is a slightly cut-down (bulk download endpoints have been removed for brevity) converted OpenAPI 2.0 definition (thus the Uber example in v2.0 could also be replaced). The response model is not fully defined.
Although it relies on a US Government department, it seems unlikely to come under direct threat from the current administration.