Is there any spec or convention on URL where one should place swagger.json (or whatever name it is agreed) so that public API of my site can be automatically discovered?
Updated 19 April 2017: The OpenAPI Wiki answer I gave previously is "for a very very very old version of the spec". The same source states that for 2.0 the standard is swagger.json, for 3.0 it changes to openapi.json.
Original answer:
The OpenAPI Wiki recommends using an /api-docs endpoint, at
least for server APIs. I've seen several sites in the wild that use
that, and it's our shop standard.
Hope that helps.
How about serving the Swagger JSON in an HTTP response body, in response to an OPTIONS request for the URL / ?
This is specifically permitted by the relevant RFC.
Further, consider implementing HATEOAS, as strongly advocated by Roy Fielding.
Okay. OpenAPI 3.0 still lacking auto-discovery mechanism, I try to propose a scheme based on some things that were already working:
https://example.com/.well-known/schema-discovery is a JSON document pointing to array of available schemas:
[
{
"schema_url": "/openapi.json",
"schema_type": "openapi-3.0"
},
{
"schema_url": "/v2/openapi.json",
"schema_type": "openapi-3.0"
}
]
If there is only one version of API, then https://example.com/openapi.json should be enough.
HTTP Headers. I remember somebody from Google proposed HTTP header for pointing to API. If you can find or remember it, please tell me.
Related
I'm thinking about trying to implementing a client for a particular json-rpc 2.0 service that could give a user some static typing guarantees. The API in question is very large, so actually writing a full-featured client by hand with all the necessary type information too big of a task for me to be bothered. However I've found via an undocumented http endpoint a large json based schema that seems to describe the entire json-rpc service fully. I'm certain I could write some sort of code generator using this specification. It is too big to paste here.
My question is, is there a standard specification for describing a json-rpc service? I've had a search around and I find a lot of dead links and the official spec[1] for json-rpc makes no mention of a standard schema definition for such a service. The schema I've found seems to be at least partially based off of the json-schema specification[2].
json-rpc
Json Schema
JSON Schema is great for defining payloads formats (you can even use it for REST APIs in OpenAPI) but indeed it won't help describe the "RPC" part, with the methods and entry points.
OpenRPC, created in early 2019, seems to be the most promising
The Ethereum Classic Labs Core (ECLC) team recently created the OpenRPC Specification, aiming to improve all blockchain dapp development. The specification emulates OpenAPI, the successful and widely adopted specification for REST APIs.
The OpenRPC Specification defines a standard, programming language-agnostic interface description for JSON-RPC 2.0 APIs.
Other approaches
Drupal JSON-RPC module provides a discovery endpoint and a Postman collection
The available RPC services along with documentation and usage details can be discovered by sending an HTTP GET request to /jsonrpc/methods.
You can use this Postman Collection with examples and tests.
There might also be interesting things to get from AsyncAPI, gRPC, GraphQL.
Dead
Also citing some other options I stumbled upon but which are dead:
JSON-WSP seems outdated, the Wikipedia page is pending deletion (talk page seems to say this was never actually a standard)
JSON-WSP (JavaScript Object Notation Web-Service Protocol) is a
web-service protocol that uses JSON for service description, requests
and responses. It is inspired from JSON-RPC, but the lack of a service
description specification with documentation in JSON-RPC sparked the
design of JSON-WSP.
JSON Schema Service Descriptor seems to have remained a draft
A JSON Schema service descriptor is simply a JSON Schema with the additional definition for methods.
A bit late but is this what you are looking for?
https://github.com/open-rpc/meta-schema/blob/master/schema.json
I’m seeing a “DynDNS2” protocol referenced a lot but
I have a hard time locating its specification. AFAICS,
RFC 2136 is not versioned on the protocol level so I’m
inclined to rule that one out. Somehow I can find
numerous implementations of DynDNS2 but the repos I’ve
browsed don’t link to a canonical document either.
Example: https://support.google.com/domains/answer/6147083
– that’s Google claiming they support this protocol without
further explanation.
Where can I find the official specification of DynDNS2?
Who is in charge of its standardization and development?
The link (now) shows how to do so "manually":
https://username:password#domains.google.com/nic/update?hostname=subdomain.yourdomain.com&myip=1.2.3.4
And gives more specs.
You should check the link to the support page again and click the Using the API to update your Dynamic DNS record
Example HTTP query:
POST /nic/update?hostname=subdomain.yourdomain.com&myip=1.2.3.4 HTTP/1.1
Host: domains.google.com
Authorization: Basic base64-encoded-auth-string User-Agent: Chrome/41.0 your_email#yourdomain.com
Also you need to add the User Agent header to make sure your call is not ignored or worse, your client is blocked.
At source forge you can find a list of these dynamic DNS "protocols".
Dyn.com has quite good documentation on their site including flow diagram, update api and return codes
The RFC 2136 spec is an extension of the DNS itself and used by nsupdate command. It's complicated and is used by sysadmins.
Routers are using just a plain HTTP GET requests to some DDNS provider. Their urls are looking the same as original Dyn.com have: /nic/update?hostname=[DOMAIN]&myip=[IP].
See:
https://openwrt.org/docs/guide-user/services/ddns/client
https://sourceforge.net/p/ddclient/wiki/protocols/
I see that in the Microsft managed REST APIs exposed in Azure there are two ways to do versioning
a) x-ms-version in header
b) api-version in query string
I wanted to understand what is the decision behind the selection between the two. I was reading somewhere that x-ms-versioning is legacy and way forward is the query string versioning mode. Is this correct?
Also as per Scot Hanselman's blog he says Query string parameter is not his preferred way and he would choose the URL Path segment. Then wondering why Microsoft adopted this option? I do agree that each person has his own preference but would be helpful to know the reason for this selection from Microsoft.
The x-ms-version header is legacy and only maintained for backward compatibility. In fact, the notion of using the x- prefix has been deprecated since the introduction of RFC 6648 in 2012.
Using api-version in the query string is one of the official conventions outlined in §12 Versioning of the Microsoft REST API Guidelines. The guidelines also allow for using the URL segment method, but the query string method is the most prolific.
Fielding himself has pretty strong opinions about API versioning - namely don't do it. The only universally accepted approach to implementing a versioned REST API is to use media type negotiation. (e.g. accept: application/json;v=1.0 or accept: application/vnd.acme.v1+json). GitHub versions their API this way.
While media type negotiation abides by the REST constraints and isn't all that difficult to implement, it's the least used method. There are likely many explanations for why, but the reality is that there are at least 3 other very common methods: by query string, by URL segment, or by header.
Pedantic musings aside, the most common forms are likely due to the ease in which a client can access the service. The header method is not much different that using media type negotiation. If a header is going to be used, then using the accept and content-type headers with media type negotiation is a better option. This leaves us with just the query string and URL segment approach.
While the URL segment approach is common, it has a few pitfalls that most service authors don't consider. It's proliferation has very much been, "Well, that's how [insert company here] does it". In my opinion, the URL segment method suffers from the following issues:
URLs are not stable. They change over time with each new API version.
As part of the Uniform Interface the URL path is supposed to identify a resource. If your URL paths are api/v1/products/123 and api/v2/products/123, it implies that there are two different products, which is not true. The v1 versus v2 URL segment is implying a different representation. In all API versions, the resource is still the same logical product.
If your API supports HATEOAS, then link generation is a challenge when you have incongruent resource versioning. Mature service taxonomies and the REST constraints themselves are meant to help evolve services and resources over time. It's quite feasible to expect that api/orders could be 1.0 and a referenced line item with api/products/123 support 1.0-3.0. If the version number is baked into the URL, what URL should the service generate? It could assume the same version, but that could be wrong. Any other option is coupling to the related resources and may not be what the client wants. A service cannot know all of the API versions of different resources a client understands. The server should therefore only generate links in the form of vanilla resource identifiers (ex: api/products/123) and let the client specify which API version to use. Any other manipulation by the client of links greatly diminishes the value of supporting HATEOAS. Of course, if everything is the same version or on the same resource, this may be a non-issue.
2 and 3 can be further complicated by a client that persists resource links. When an API version is sunset, any old links to the resource are now broken, even though the resource still exists albeit not using an expected, but obsolete representation.
This brings things full circle to the query string method. While it's true that the query string will vary by API version, it's a parameter not part of the identifier (e.g. path). The URL path stays consistent for clients across all versions. It's also easy for clients to append the query parameter for the version that they understand. API versions are also commonly numeric, date-based, or both. Sometimes they have a status too. The URL api/products/123?api-version=2018-03-10-beta1 is arguably much cleaner than api/2018-03-10-beta1/products/123.
In conclusion, while the query string method may not be the true RESTful method to version a resource, it tends to carry more of the expected traits while remaining easy to consume (which isn't a REST constraint). In conjunction with the Microsoft REST API Guidelines, this is why ASP.NET API Versioning defaults to the query string method out-of-the-box, even though all of these methods are supported.
Hopefully, this provides some useful insights as how different styles can affect your service taxonomy aside from pure preference.
I am planning to write a RESTful API and I am clueless how to handle versioning.
I have read many discussions and blog articles, which suggest to use the accept header for versioning.
But then I found following website listening popular REST APIs and their versioning method and most of them using the URL for versioning.
Why?
Why are most people saying: "Don't use the URL, but use the accept header", but popular APIs using URL?
Both mechanisms are valid. You need to know your consumer to know which path to follow. In general, working with enterprises and academically-minded folks tends to point developers towards Resource Header versioning. However, if your clients are smaller businesses, then URL versioning approach is more widely used.
The Pros and Cons (I'm sure there are more, and some of the Cons have work-arounds not mentioned here)
It's more explorable. For most requests you can just use a browser, whereas, the Resource Header implementation requires a more programatic approach to testing. However, because not all HTTP requests are explorable, for example, POST requests, you should use a Rest Client plugin like Postman or Paw. URI Pro/Header Con
With a URI-versioned API, resource identification and the resource’s representation is munged together. This violates the basic principles of REST; one resource should be identified by one and only one endpoint. In this regard, the Resource Header versioning choice is more academically idealistic. Header Pro/URI Con.
A URI-versioned API is less error prone and more familiar to the client developers. Versioning by URL allows the developer to figure out the version of a service at a glance. f the client developer forgets to include a resource version in the header, you have to decide if they should be directed to the latest version (which can cause errors when incrementing the version) or a 301 (Moved Permanatly) error. Either way there is more confusion for your more novice client developers. URI Pro/Header Con
URI versioning lends itself to hosing multiple versions in the same application. In this case you do not have to further development your framework.
Note: If you do this your directory structure will most likely contain a substantial amount of duplicate code in the v2 directory. Also, deploying updates requires a system restart - Thus this technique should be avoided if possible. URI Pro/Header Con.
It is easier to add versioning to the HTTP Headers for an existing project that didn't already have versioning in mind from it's inception. Header Pro/URI Con.
According to the RMM Level 3 REST Principle: Hypermedia Controls, you should use the HTTP Accept and Content-Type headers to handle versioning of data as well as describing data. Header Pro/URI Con.
Here are some helpful links if you want to do some further reading:
Martin Fowler's description of the Richardson Maturity Model
API Versioning - Pivotal Labs
HATEAOS
Informit.com's Article on Versioning REST Services
I am designing a REST API for a web application. I want to clearly version the API, so that the interface can be changed in the future without breaking existing services. So in my v1.0 API, I want to clearly identify it as the v1.0 API, leaving me the freedom to release a future v1.1 version with breaking changes.
My question is, would a period in the path component of a URI be bad practice?
eg. Is there any good reason not to use http://example.com/myapi/v1.0/services as a URI to my service?
Putting a period in the URI is perfectly fine. Putting a version number in an URI is definitely not a best practice.
Here are my reasons why and here is an good article on the subject by someone much smarter than me.
It is perfectly acceptable to use a period in a URI path. It is also valid as per RFC 3986 section 2.3.
its a perfectly valid path character, see page 27 of the spec http://www.ietf.org/rfc/rfc2396.txt
No reason not to use it
I think differently of the others... I don't think it is a good practice to use it on the url.
IMHO it is way better if you version on the Content-Type Header.
As an example, if you are using application/xml:
Content-Type: application/v1.0+xml.
Using the Content-Type, it also indicates that the resource itself is versioned. While if you use it on the url it seems that you are versioning the service (which doesn't seem to be so), and if you are changing the service itself you will probably change the url, so you don't need the version number.
EDIT: You should also use it on the Accept Header, not only on the Content Type.
I think it is a good idea. I've seen several rest services that do this.