darrelmiller

The site is back, but I this was a sufficient kick in the ass to finally get the blog moved onto a proper platform.

Well that's embarrassing.

Hence the reason for tools like swagger-inflector http://swagger.io/writing-apis-with-the-swagger-inflector/ that allows you to drive routing directly from the OpenAPI definition

The text is different but the meaning is the same. A GET body must not have an effect on the request/response. i.e. You can have one, but you are not allowed to use it for anything.

We use OpenAPI in many other places too. Azure Logic Apps, Azure API Management, Azure Functions, Azure API Apps, Microsoft Flow, PowerApps. And the list just keeps getting longer. Also, the new Microsoft Docs site is driven off OpenAPI.

We have been having numerous conversations within Microsoft to figure out how to describe Graph API using OpenAPI. The new Links capability helps a lot. Also, the AnyOf support will help with describing URLs with Expand. There are still a bunch of issues to work out.

You are correct that the Swagger name is owned by Smartbear, however, whereas previously Swagger was used to name tooling and the specification, now Swagger only refers to the tooling built by Smartbear. OpenAPI V2 and V3 is the name of just the specification. Saying that they are the same thing causes more confusion than has already been created.

It makes it hard to take advantage of HTTP caches. There is also some redundancy because SOAP has headers and HTTP has headers. Which to use? It also is handy to be able to make idempotent requests, especially over flakey networks.

The one distinction that I think is worth making is that OpenAPI describes HTTP APIs using the semantics of HTTP. Corba and SOAP attempted to be protocol independent. That's much harder to do well. Another good aspect of OpenAPI is that most people who are using it, are starting towards using the definition as the primary design artifact and then letting tooling work on that. Almost no-one designed WSDL or IDL by hand. Focusing on an OpenAPI as a design contract helps developers produce solutions that are more independent of tooling. And that's a good thing.

This issue list on the OpenAPI GitHub repo is full of requests for change. The spec hasn't changed in a long time, and although this is a fairly big change, it shouldn't be a particularly difficult change for tooling folks to adapt to. This isn't a new standard, it's just a new name, with some fixes and some new features.

By declaring conformance to YAML 1.2 and requiring conformance to the JSON Schema ruleset defined in YAML 1.2 we can ensure that any YAML OpenAPI document can be converted into JSON without any loss of information.

OpenAPI V3 now supports AnyOf and OneOf constructs from JSON Schema.

We're not :-)

Yes, we decided to be opinionated and say you can't describe bodies for operations where the spec says bodies have no meaning. The text should be there, but I think the RC0 revision has some formatting issues that is hiding the text.

Hey Gregory, thanks for the article. Would it be possible to change your title to OpenAPI 3 and not Swagger 3.0? Swagger is the name of the tooling produced by Smartbear that supports OpenAPI and they just released new versions of their Swagger tooling, but it's not the same thing as OpenAPI 3.0. Yes I know it is confusing :-)

They thought about it...

"Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables. Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression. In general, regular expression languages are better suited for variable matching."

For some additional insight on accept based conneg. The guys who created it, really wish they hadn't.

http://www.alvestrand.no/pipermail/ietf-types/2006-April/001...

"Regarding proactive negotiation in HTTP/2, I'll note that Waka strips all negotiation fields. I find the entire feature revolting, from every architectural perspective, and would take the opportunity of 2.x to remove it entirely." Roy Fielding http://lists.w3.org/Archives/Public/ietf-http-wg/2013JanMar/...

Link relations can be designed that indicate which HTTP methods are allowed. HAL is heavily dependent on conveying semantics via link relations, which is something that some people don't like doing.

Consider the oauth2-token link relation defined here[1]. The definition of this link relation refers to RFC 6749 [2] which states that it is necessary to pass a application/x-www-form-urlencoded body using POST.

[1] https://tools.ietf.org/html/draft-wmills-oauth-lrdd-07#secti... [2] https://tools.ietf.org/html/rfc6749#section-4.1.3

By having a framework "handle this" you teach novice devs that they don't have to think about it and then they do stuff the framework can't fix and wonder why the framework is broken!

Web API is actually built on a completely different HTTP pipeline than ASP.NET products. When it moved to the ASP.NET team, there were a number of changes made to make it feel more natural to ASP.NET devs. Hence the slight variations when you dig under the covers. The question we need to ask ourselves, is why would the ASP.NET team agree to continue to support a completely new HTTP pipeline.

If you like Jinja2 then use it. We have been using it for templating, running with IronPython, for the last couple of years.