I read tons of documentation about pros and cons of URI versioning against Header (media type) versioning (Best practices for API versioning?).
If I want to chose the media type versioning what's the best way to document my API?
I'm using Swagger (2.0) and I looked also into OpenAPI 3.0 but I couldn't find an easy and clear way to exposes different versions for the same endpoint.
I'd like to have a clear and easy understandable way to share my API definitions with my integrators.
Related
I'm looking to get familiar with the Amazon Connect API. I've seen the reference below but it's difficult to use for me because the navigation is a flat, alphabetical list of endpoints ordered by action instead of resource. Of note, the endpoints are alphabetized beginning with "Delete", Get", "List", "Update" and others, while it would be great to have these grouped by resource.
I'd like to reorganize the docs which can be done by editing an OpenAPI or other API specification and adding tags for each operation. I looked though the reference and conducted a few searches unsuccessfully.
I'm using the following API Reference:
https://docs.aws.amazon.com/connect/latest/APIReference
Any other spec format such as RAML or a proprietary format would be okay as well. For example, Google provides their own "Google Discovery Format" which can be converted to OpenAPI. The following is mentioned at https://googleapis.github.io/ .
OpenAPI
We recommend using OpenAPI and OpenAPI-based tools for working with Google’s REST APIs. Several tools for converting Google Discovery Format to OpenAPI have been published:
google-discovery-to-swagger, an MIT-licensed open source script for converting Google Discovery format into Swagger 2.0.
API Spec Converter, an online converter from LucyBot.
The API Transformer from APIMatic.
Google’s OpenAPI tools include gnostic, a front-end for OpenAPI tools that reads OpenAPI descriptions, puts them in an efficient binary representation, and allows efficient plugins and standalone tools to be easily written in any programming language with Protocol Buffer support.
Is there an OpenAPI or other spec available for this API? If there is, I'd like to update it with tags and then render it in an easier to consume format.
Update: Aossey notes that Amazon doesn't publish OpenAPI specs for their APIs. To address this, I've started to assemble some information in the repo below, potentially resulting in an OpenAPI spec. Feel free to contribute.
https://github.com/grokify/amazon-api-specs/blob/master/connect/endpoints.csv
The short answer is no, there is no OpenAPI spec for these APIs.
These functions (listed in the docs you linked) are implemented in AWS SDK and the AWS CLI. While there are underlying HTTP endpoints, they are not easily consumable in the way you're most likely looking for. The SDK and CLI take care of authentication/authorization (via IAM service) and request signing for you, which you would have to implement yourself if you were going to leverage the endpoints directly.
Currently I am working on a REST API and noticed, that for real REST it is essential to provide the possible HTTP operations of the resource within the HTTP response (e.g. in JSON-LD format).
After playing around with Swagger, I got to JSON-LD and Hydra, which in combination provide the foundation for real REST.
The problem with pure JSON-LD and Hydra is, that there is no real editor (the Playground does help for testing but not for editing).
Then I found Api Platform which sounds quite promising but I could not find any hint, that it supports real REST.
Does API Platform support HATEOAS in terms of providing the possible HTTP operations?
API Platform explicitly supports HATEOAS and they even encourage using Hydra. Their admin UI supports viewing the API through an OpenAPI lens or a Hydra lens.
We are generating API documentation from the source code using Swagger. I am now wondering if there is any tool which automatically checks the compliance of the generated OpenAPI document (= Swagger JSON) to RESTful API design best practices.
For example Zalando has defined a publicly available guideline for REST-design In my opinion in these guideline there are many rules which can be check automatically based on the OpenAPI Specification:
“Don’t Break Backward Compatibility” could be check when OpenAPI
documents of different versions are compared.
“Always Return JSON Object as Top-Level Data Structures to Support
Extensibility"
“Keep URLs Verb-Free” could possible checked if compared with
dictionaries.
…
So far, I only found tools which checks the completeness and naming conventions of an OpenAPI document. Does someone know a tool with more advanced rules?
UPDATE:
Meanwhile I have found a tool called Zally (https://github.com/zalando-incubator/zally). This tool checks for violations of Zalando's REST-Api Guidelines. It is rather easy to configure or extend.
Some of these could be added as rules to openapilint. The backward compatibility check would need to compare two spec versions in search of differences, which is a bit more complex.
I have found some strategies for versioning REST APIs via SO and Google etc., but I have not found any strategies for versioning internal REST apis (and I mean by this, that I intend making a web app, an Android app etc that share a common REST api, but the general public will not get access to the API).
Seeing as the API is for internal use only, it would need less backwards compatibility, and basically a way of being 'current' and 'edge' or something similar. Any tips on a nice and simple strategy to version an internal REST api for minimal hassle would be great.
current is a very bad way to differentiate. If you have an application which carries out a call to /current/users, and then you upgrade your API so that /current/users returns different information, your application will break.
Stick with versioning. A simple /v1/users is clear and concise, and when you add /v2/users then the applications using the old API endpoint will continue to work and you can update them as and if you require.
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