Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Evaluate OpenAPI Specification as a common API description format #31

Closed
benh-gds opened this issue Dec 15, 2016 · 58 comments

Comments

@benh-gds
Copy link

commented Dec 15, 2016

Evaluate OpenAPI as a standard for describing APIs

Can OpenAPI be the standard used to describe APIs?

Category

  • Data
  • Document
  • Technical
  • Other Suggestions

Challenge Owner

I'm Ben Henley, a tech writer for GaaP

Short Description

OpenAPI/Swagger is a standard way to describe APIs. It provides a machine-readable description of an API which can be generated by the developers who work on the API. Swagger can be used to generate parts of the documentation, and to create tools like interactive API explorers. There are many tools available which understand Swagger. This makes it easier to maintain accurate documentation and update it quickly. At least two GDS projects already have Swagger descriptions of their APIs.

User Need

Developers who use government APIs need accurate documentation. If all projects that produce APIs were required to maintain a Swagger description, it would make it easier to introduce common documentation tools and make documentation more accurate.

Expected Benefits

Developers would benefit from more accurate API documentation and improved ways to learn about the APIs, like interactive tools. API documentation would be standardised and consistent between projects, reducing time spent for developers to find the information they need. This will increase trust in documentation and reduce time spent on support and increase the pace of integration. Tech writers will need to spend less time maintaining documentation. A Swagger description may also be required for other API-related tools, like monitoring services, management tools and API gateways.

Functional Needs

Teams must be able to produce and maintain Swagger descriptions of their APIs.

@edent

This comment has been minimized.

Copy link
Contributor

commented Dec 19, 2016

Thanks @benh-gds - this looks like a great candidate for us. We'll start to look into this now.

@jystewart

This comment has been minimized.

Copy link
Contributor

commented Dec 20, 2016

The Swagger spec has been renamed to be the OpenAPI spec - https://github.com/OAI/OpenAPI-Specification - which is what we should use. As I understand it Swagger should now be considered as a set of tools for working with the OpenAPI spec. The separation is important as our Open Standards focus should be on the standard by which the information is recorded/conveyed, and not on the tooling or processes that produce it.

OpenAPI is up to version 2.0. Work is underway on 3.0 but it's not clear (from my very brief exploration) how close that is or what changes it introduces. It would be good to have a clear picture of that so we can focus our review.

I know that teams in GDS and Companies House (who have a fork of swaggerly) have been working with Swagger and/or OpenAPI. There have also been ad-hoc conversations with other government teams but it'd be good to solicit more opinions from them here.

@benh-gds

This comment has been minimized.

Copy link
Author

commented Dec 20, 2016

@edent edent changed the title Evaluate Swagger as a common API description format Evaluate OpenAPI Secification as a common API description format Dec 20, 2016

@edent

This comment has been minimized.

Copy link
Contributor

commented Dec 20, 2016

I've updated the issue to reflect that it's OpenAPI that we wish to evaluate.

OAI 3.0 is currently being designed. As this will be a breaking change with 2.x, I think we should focus our evaluation on 3. See https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next

Some further reading at https://www.infoq.com/articles/open-api-initiative-update

@edent

This comment has been minimized.

Copy link
Contributor

commented Dec 21, 2016

To address some concerns that people have raised with me offline.

  • This is not telling people how to write their APIs. This challenge is around clear and consistent documentation of existing and new APIs.
  • This is not insisting on which verbs or methods to use.
  • This is not tying us in to a specific response format (JSON, XML).
  • This is not standardising the look & feel of the APIs, nor where they live.
  • This is not a decision on OAI v2 or v3. As we do our discovery, we'll have to see what the timescales are for v3 and whether it will be backwards compatible with v2 documentation.
This was referenced Jan 5, 2017

@edent edent added the in progress label Jan 5, 2017

@edent

This comment has been minimized.

Copy link
Contributor

commented Jan 9, 2017

We have some research from @RosalieDM around this. Will share in public once suitably redacted.

@edent

This comment has been minimized.

Copy link
Contributor

commented Jan 9, 2017

@edent

This comment has been minimized.

Copy link
Contributor

commented Jan 9, 2017

Presentation given to MoJ about the research we've done on the need for good documentation.

FOR MOJ Presentation for Documenting APIs.pdf

@edent

This comment has been minimized.

Copy link
Contributor

commented Jan 9, 2017

This is what our discovery around user needs found. Not all of this is directly relevant to a documentation standard, but provides several useful pieces of evidence.

This research was conducted on internal and external users, with various levels of experience.

Developer API documentation user needs

These are the needs developers and tech archs have when it comes to API documentation.

Each point contains ideas on how to meet these needs (all put forward by developers and tech archs themselves).

1)   I need a quick way to start using the API

  • Code examples and some kind of API explorer/Sandbox are necessary.
  • Developers need to quickly identify the API reference info (the calls and responses) from the accompanying developer docs (the concept, security, cost info). This can be helped with hierarchy to content vs flat content structure.
  • Different languages/code libraries are useful (this is where a 3 column design like Stripe has  - can be useful).

Most user docs are aimed at the average user, with beginners directed to tutorials/training and advanced users to forums. So there is the issue of what knowledge the average user is presumed to have (and therefore omitted).

2)   I need to experiment with the API before I sign up

  • Sandbox and code examples are important.
  • Screen width of documentation should be expandable so devs can have multiple windows open at once.

3)   I need to be able to quickly search the documentation

  • Devs tend to use control F to search docs so it makes sense to have documentation on one page.

Is this true? A lot of API documentation is created using a flat file CMS, and these don't tend to have a built-in search function. The workaround has been to put all the content onto a single page, so the user can use Control F to search. If it were possible to search the content using a better Search than the default flat file CMS's, would users use that instead/in addition to Control F?

  • Always visible index.
  • Content clearly labeled with content in hierarchy (no flat content).
  • Clear headers.

4)   I need to quickly understand how the product works

  • Developers need to be able to search the documentation easily, eg with control F (needs docs all on one page), always visible index.
  • Architecture diagrams are important.
  • Content should be friendly rather than formal.
  • Clear concept/intro to product section & architecture section.
  • Rate limiting info

5)   I need a way to assess a product/ I need to know how to classify product, eg whether its something I build or buy

  • Clear concept/intro to product section, outlining whether the product is to be built, bought, etc.
  • Up to date versioning information (this can be automated), security information and cost information.
  • If product is part of a portfolio, the docs should link to the other products’ API docs (all the API docs could be part of a hub).

6)   I need to know whether the API is right for my service

  • Case studies can be very useful.
  • Contact details.
  • Clear description of how the product works (see above).
  • Detailed info on cost and security.
  • Rate limiting info.

7)   I need to know I can trust the API / I need to know the API is reliable and secure

  • Clear security info.
  • Versioning info.
  • Up to date documentation – use of Swagger or equivalent.
  • Rate limiting info.
  • If product is part of a portfolio, the docs should link to the other products’ API docs (all the API docs should be part of a hub).

8)   I need to know the API documentation is up to date/ I need to know if changes happen to the technologies I’m using/ I need to make sure I don’t let the product become out of date/ I need to know which version of the product I’m using.

  • Clear/automated way of letting users know about changes to API.
  • Clear versioning info (comes from use of automated doc tools).
  • API docs clearly labeled with when they were last updated.

9)   I need to know whether I can recommend the API

  • Documentation should be clear, accessible and up to date (use of automated tools).
  • API needs to be easy to use.
  • Authentication should be simple and documentation should cover how to authenticate clearly.
  • Very good sandbox functionality.
  • Clear contributor guidelines and how to get involved advice.
  • Rate limiting info.

10)   I need to know how to make difficult updates to the product I’m using

  • Detailed information in the docs, clearly labeled with hierarchy to content/clear signposts.
  • Contact info.
  • Contributor community and info on how to get involved with this.

11)  I need to know there’s support available when I use the info/ I need to feel involved in the API community/ I need to report problems with the API.

  • Contact info.
  • Contributor community and info on how to get involved with this.
  • Service helpdesk, eg deskpro.
  • If product is part of a portfolio, the docs should link to the other products’ API docs (all the API docs should be part of a hub).

12) I need to understand when I’ve made a mistake connecting to the API

  • Error code information.
  • Consistently communicate your API endpoints (this should minimize back-and-forth-confusion-about what-call-does-what).See this info written by a contractor at CH - this could be enforced with the API doc tool, or done with markdown.

13)    I need to be able to abide by the government’s data sharing agreements

  • Mark this clearly in the documentation.

API doc tool needed features

  1. Sandbox functionality
  2. Ability for API docs to be part of a hub
  3. Hierarchy to content
  4. Integration of automated doc tools
  5. Change alert system
  6. Code examples
  7. Different languages - 3 column design?
  8. Doc screen width expandable
  9. Docs all on one page
  10. Always visible index

@Lawrence-G Lawrence-G changed the title Evaluate OpenAPI Secification as a common API description format Evaluate OpenAPI Specification as a common API description format Jan 30, 2017

@edent

This comment has been minimized.

Copy link
Contributor

commented Jan 30, 2017

Looping @timblair into the conversation as this will affect APIs that he manages.

@timblair

This comment has been minimized.

Copy link
Member

commented Jan 31, 2017

Looks like a preview release of v3 of the OAI spec is due at the end of February.

@simon-cutts

This comment has been minimized.

Copy link

commented Feb 6, 2017

From our perspective in DVSA, documenting API's in standard format is a must. Initially we settled upon RAML because it seemed to offer more features than Swagger. Our view has now switched to OpenAPI because the feature set has caught up with RAML, but more importantly, OpenAPI has wider adoption. I have a clunky SOA background where people would be shot if they did not have a service contract in the form of a SOAP WSDL. So in, in short, +1 for OpenAPI

@Lawrence-G

This comment has been minimized.

Copy link
Contributor

commented Feb 7, 2017

As part of our evaluation of OpenAPI these are the assessment questions and answers.

OpenAPI* Specification* v2.0 (we anticipate most answers will also apply V3.0 )
*previosly known as Swagger

Applicability

Q. Does the formal specification address and facilitate interoperability between public administrations?

Yes
A standardised documentation format for describing REST APIs produced in public administrations would promote consistency in APIs. This would be achieved by making the documentation easier to work with, to maintain and to share. It would also allow common tools to be used for working with and maintaining APIs

Q. Does the formal specification address and facilitate the development of information or IT systems in government?

Yes
This standard Supports the development of RESTful APIs.

Q. Are the functional and non-functional requirements for the use and implementation of the formal specification appropriately detailed?

Yes
All requirement are specified in the standard specification

Q. Is the formal specification applicable and extensible for implementations in different domains?

Yes
The standard is applicable to any domain where REST APIs are used

Q. Is the formal specification largely independent from products of single providers (either open source or proprietary)?

Yes
Not bound to a single provider

Q. Is the formal specification largely independent from specific platforms?

Yes OpenAPI Aims to be a language-agnostic interface to REST APIs

Q. Has the standard been written such that its realisation can be/is demonstrated using more than one technology (e.g. XML and JSON)?

Yes
File format is JSON and YAML for specification files.

Maturity

Q. Has the formal specification been sufficiently developed and in existence for a period to overcome most of its initial problems?

Yes
Development started in 2010. now at V2.0. V.3.0 is due for publication in Feb 2017

Q. Are there existing or planned mechanisms to assess conformity of the implementations of the formal specification (e.g. conformity tests, certifications, plugfests etc)?

Yes
The swagger editor can be used to validate OpenAPI content
The Swagger site has these tools

Q. Has the formal specification sufficient detail, consistency and completeness for the use and development of products?

Yes
The specification has been used in documenting numerous APIs

Q. Does the formal specification provide available implementation guidelines and documentation for the implementation of products?

Yes
The standards wiki contains this information -
https://github.com/OAI/OpenAPI-Specification/wiki

Q. Does the formal specification provide a reference (or open source) implementation?

Yes
There is an example implementation, an interactive UI http://petstore.swagger.io/

Q. Does the formal specification address backwards compatibility with previous versions?
Migration guides for versions are available
https://github.com/OAI/OpenAPI-Specification/wiki/1.2-transition

Q. Have the underlying technologies for implementing the formal specification been proven, stable and clearly defined?

Yes
All the underlying technologies are widely used and proven e.g JSON HTML XML

Openness

Q. Is information on the terms and policies for the establishment and operation of the standardisation organisation publicly available?

Yes

see - https://www.openapis.org/participate/how-to-contribute/governance

Q.Is participation in the creation process of the formal specification open to all relevant stakeholders (e.g. organisations, companies or individuals)?

Yes - see this post
The Technical Developer Community is open to any developer, end user or subject matter expert that chooses to participate in the activities of OAI (Open API Initiative)

Q. Is information on the standardisation process publicly available?
Yes
https://www.openapis.org/participate/how-to-contribute/governance

Q. Information on the decision making process for approving formal specifications is publicly available?

Yes
https://www.openapis.org/participate/how-to-contribute/governance

Q. Are the formal specifications approved in a decision making process which aims at reaching consensus?

Yes
https://www.openapis.org/participate/how-to-contribute/governance
“The intention is for the OAI to operate by consensus. However, if consensus cannot be achieved, the Business Governance Board shall vote on a decision. “

Q. Are the formal specifications reviewed using a formal review process with all relevant external stakeholders (e.g. public consultation)?

Yes
Review on GitHub by voting on issues and pull requests using reaction function

Q. All relevant stakeholders can formally appeal or raise objections to the development and approval of formal specifications?

Yes
Through the Technical Oversight Board https://www.openapis.org/participate/how-to-contribute/governance#TDC

Q. Relevant documentation of the development and approval process of formal specifications is publicly available (e.g. preliminary results, committee meeting notes)?

Yes
Through GitHub -
“TDC strives to communicate through issues and pull requests, we’re all volunteers that steal time to work on OpenAPI. Sometimes it’s faster to have an hour long conference call, which we do every couple of weeks. In addition, we use the OAI’s Slack team to raise attention to questions or suggestions when GitHub notifications don’t get the job done. The changes proposed by a sub-issue in a meta issue result in a pull-request (PR), and that PR is then voted on by using a reaction on the issue.”
TDC Technical Developer Community

Q. Is the documentation of the formal specification publicly available for implementation and use at zero or low cost?

Yes
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

Intellectual property rights

Q. Is the documentation of the IPR for formal specifications publicly available (is there a clear and complete set of licence terms)?

Yes
Documentation - Apache License, Version 2.0 - ( note specification and documentation are equivalent for OpenAPI )

Q. Is the formal specification licensed on a royalty-free basis?
Yes
Apache License, Version 2.0 -
Grants a “worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

Market support

Q. Has the formal specification been used for different implementations by different vendors/suppliers?

Yes
The specification is widely used by API developers and the are a number of tools that can render and parse OpenAPI specification document.

Q. Has the formal specification been used in different industries, business sectors or functions?

Yes
Organisations from a number of sectors use and contribute to the specification -
Contributing members - https://www.openapis.org/membership/members

Q. Has interoperability been demonstrated across different implementations by different vendors/suppliers?

Yes
Several vendors supply tools to work with the specification when building APIs

Q. Do the products that implement the formal specification have a significant market share of adoption?

Yes
Thousands of API’s are using the specification

Q. Do the products that implement the formal specification target a broad spectrum of end-uses?

Yes
Not tied to a particular product or end user group.

Q. Has the formal specification a strong support from different interest groups?

Yes -
see members list.

Potential

Q. Is there evidence that the adoption of the formal specification supports improving efficiency and effectiveness of organisational process?

Yes
The specification avoids errors in documentation that can then lead to APIs not behaving as expected.

Q. Is there evidence that the adoption of the formal specification makes it easier to migrate between different solutions from different providers?

Yes
Spec is applicable to APIs and tools from any provider.

Q. Is there evidence that the adoption of the formal specification positively impacts the environment?

Not applicable.

Q. Is there evidence that the adoption of the formal specification positively impacts financial costs?

Yes
It should do as errors in docs and no API documentation costs time.
API documentation saves developer time when maintaining or building on existing APIs
Developer time is expensive but it will be difficult to put a figure on the cost.

Q. Is there evidence that the adoption of the formal specification positively impacts security?

Yes
Though not strictly concerned with security It is anticipated that the improving documentation will make it simpler to analyse the security of an API
The specification supports authorisations schemes e.g. OAuth2.

Q. Is there evidence that the adoption of the formal specification can be implemented alongside enterprise security technologies?

Yes
OpenAPI specification supports three authorisation schemes - basic authentication, API key and OAuth2.

Q. Is there evidence that the adoption of the formal specification positively impacts privacy?

No
Probably no impact on privacy

Q. Is the formal specification largely compatible with related (not alternative) formal specifications in the same area of application?

Yes
OpenAPI Specification is language-agnostic. It is also extensible into new technologies and protocols beyond HTTP

Q. Is there evidence that the adoption of the formal specification positively impacts the accessibility and inclusion?

Not applicable

Q. Does the formal specification have a defined maintenance organisation?

Yes

OPEN API initiative

Q. Does the maintenance organisation for the formal specification have sufficient finances and resources to be sure of freedom from short- to medium-term threats?

Yes
Is a Linux Foundation Collaborative Project independently funded software project.
The Linux Foundation shall have custody of and final authority over the usage of any fees, funds and other cash receipts.
Members of the initiative include Google, Adobe, IBM, PayPal, Microsoft, which indicates a security in resources for the foreseeable future.

Q. Does the maintenance organisation have a public statement on intention to transfer responsibility for maintenance of the formal specification if the organisation were no longer able to continue?

No
None that we have found, though it is assumed this would be through the Linux Foundation

Q. Does the formal specification have a defined maintenance and support process?

Yes
Support is via GitHub
Overseen by Technical Developer Community and Technical Oversight Board https://www.openapis.org/participate/how-to-contribute/governance
Q.Does the formal specification have a defined policy for version management?

Yes
The latest version of the specification can be found on GitHub.
https://github.com/OAI/OpenAPI-Specification/tree/master/versions
The difference between versions and migration documentation are published on GitHub.

Coherence

Q. Is this an existing European standard or an identified technical specification in Europe? (Note: CEN, CENELEC and ETSI are the European standards bodies. Technical specifications provided by organisations other than CEN, CENELEC or ETSI can be under consideration to become a European standard or an identified technical specification in Europe for example through the Multi Stakeholder Platform.)

No.

Q. Does this specification or standard cover an area different from those already identified or currently under consideration as an identified European standard or specification?

Yes
As far as our research shows

@jontybale

This comment has been minimized.

Copy link

commented Feb 20, 2017

Just to jump in here and provide some additional thoughts - I am currently working on some proof of concepts internally at the DWP for documenting APIs using OAS, including the development of an API Hub - very early days however but we do see the adoption of a documentation standard such as this very useful.

I personally have found OpenAPI/Swagger to be vital when designing APIs and discussing proposed implementations with colleagues - prior to using OAS I would normally document API endpoints in a Google sheets and circulated it for discussion.

It just gives you a clean, declarative, common language in which to discuss API specifications.

As to when to use OAS - I have found that the best option has been to create an up front spec as a stand alone file when designing a service, then transition to annotations once the work to deliver an endpoint is completed.

@davidcarboni

This comment has been minimized.

Copy link

commented Feb 26, 2017

I thought I'd add a couple of counterpoints. To be clear, the benefits are pretty compelling and well covered above, so this is about adding to the discussion by acknowledging costs rather than making a case for doing something different. I'm interested to know if these resonates and if there are other costs worth considering:

  • Complexity: I can't write a spec from memory using OpenAPI. I have to use tools or work through the documentation. This adds a level of friction for creating and updating docs.
  • Correctness: Synchronising documentation and implementation is a perennial problem, but could be more acute the more machine-readable things are - e.g. as a user, do you really want to be reverse engineering and modifying auto-generated client code if the docs are slightly out of date?
  • SOAP: There's something chilling about auto-generation of server and client code (why make it machine readable otherwise?). If it's complicated enough that generating code is on the table, maybe the focus should be on reducing complexity rather than developing better tools.

In an ideal world, developer-friendly (i.e. human readable) 'just good enough' documentation would be generated from your actual production code on Github with minimal effort and structure in the code itself. I'm nodding to Javadoc as the original and Python doc strings, with a sprinkling of annotations along the way.

It's a question for API developers everywhere and not specific to government, but government can support and influence for simple, clear standards.

@simon-cutts

This comment has been minimized.

Copy link

commented Feb 27, 2017

Writing a spec like OpenAPI with a tool is a good thing, right? A tool abstracts you away from having to retain all the complexities of the spec in your head. In my experience, specs generated from annotations tend to be light on detail. Also, not all tech supports annotation for SoapAPI. For instance, we are using AWS severless tech like API Gateway and Lambdas; API Gateway can work with an existing OpenAPI, but neither Gateway or Lambda's support annotations.

@edent

This comment has been minimized.

Copy link
Contributor

commented Mar 1, 2017

Our current plan is to take this through the approval process once v3 has been released.

The release candidate is available, and I would encourage all of you to read and leave feedback.

https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md

@timgent

This comment has been minimized.

Copy link

commented Jun 6, 2017

Sorry for coming in late, and I'll admit to not having read all the good detail in this thread. I think the OpenAPI spec is a good candidate, though wanted to mention that for producing rich documentation for APIs I do think there are other options. The one we've used has been Rest-assured with Spring RestDocs (not actually limited to Spring). They are Java libraries though so limited. We have a brief write up of some of this here:
https://github.com/UKHomeOffice/api-guide-for-developers#a-name-documentationacceptance-tests-documentation-and-creating-a-mock-of-your-api

I realise this approach has drawbacks too, not least that it is limited in consistency across languages. Also hopefully we'll get tools built on OpenAPI spec at some point that allow richer, more flexible documentation where needed.

@edent

This comment has been minimized.

Copy link
Contributor

commented Aug 1, 2017

The specification has been finalised! Press Release

We will now begin consulting on whether to mandate this as the way to document APIs.

Full specification https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

@psd

This comment has been minimized.

Copy link

commented Aug 1, 2017

My biggest concern is that the challenge is to around improving documenting a class of APIs, but by From a quick attempt to use it to describe the register API, it seems whilst OpenAPI works well for RPC interfaces, it can't describe hypermedia interfaces which span multiple domains. I worry about other common HTTP patterns which can't be described and which would be precluded if this specification was mandated as an open standard.

@pwin

This comment has been minimized.

Copy link

commented Aug 1, 2017

I agree with the caution from @psd about any mandate precluding descriptions. This could leave holes in documentation.

Also, I've not noticed in the openAPI scope for wrapping XML Schema components for defining request or response (it seems to do JSON) whereas RAML 1.0 does.

@edent

This comment has been minimized.

Copy link
Contributor

commented Aug 1, 2017

Thanks @psd - do you have any specific examples of common HTTP patterns which you think will be a problem?

I agree that, based on this issue at OAI, that HATEOS might be problematic. Would it be enough to say that this is the standard for REST APIs?

It appears that v3 supports multiple servers - is that what you mean by multiple domains?

@puntofisso

This comment has been minimized.

Copy link

commented Aug 1, 2017

I must concur with the comments so far.
I have used Swagger since version 2 to document the API behind data.sgul.ac.uk and on several freelance projects and it's good - assuming your API is fully REST.

The framework is powerful and a great tool for your developers/users, especially as it allows the generation of "live" API docs (where the devs can try it out), and it's easy to translate into other formats (e.g. via XSLT etc). However, I remember looking into documenting SOAP services and I could not find much in this direction.

You might as well argue that a SOAP service requires an entirely different approach. Therefore, I would recommend OpenAPI/Swagger if you were to suggest its adoption as a standard to document REST API alone.

Notwithstanding our comments, you might want to have a chat with the guys behind the US data.gov, as they developed and released an API Management System called API-Umbrella. They were trying to build Swagger capabilities into it (NREL/api-umbrella#211). Last time I spoke with them, they seemed quite keen on talking to compare strategies with people this side of the pond.

@PeterParslow

This comment has been minimized.

Copy link

commented Aug 7, 2017

(from Michael Gordon of OS:)
I would endorse the main points in this thread:

• OpenAPI is a good standard for machine readable documentation and has good tooling support to generate other docs, tests etc. of it. It seems to be generally winning in terms of adoption
• Use of any particular documentation standard should absolutely not constrain API design itself and should only be used where appropriate.

I would add that:

• OpenAPI specs are not a replacement for human readable documentation and help. They should complement this. In an ideal world they form the basis that other documentaiton is built off of (whether that’s automated or manual).

We’re using OpenAPI in the Cityverve public API workgroup, and I believe there are moves afoot to utilise it in some OGC stuff (potentially some testbed things).

@SteveMarshall

This comment has been minimized.

Copy link

commented Aug 7, 2017

(Cross-posting from the community mailing list, at @edent's request)

We’re using OpenAPI in a few places in MOJ. I’m still yet to be convinced it’s good enough to be government’s (or even MOJ’s) chosen standard for documenting all our APIs, though. The API documentation space is very actively in flux right now (with OpenAPI, JSON API, and others actively being developed), so it might be a bit premature to pick a single standard.

A few things about OpenAPI concern me, based on what I’ve seen so far:

  • v3 doesn’t have a schema yet, so programmatically validating v3 documents requires the people doing the validation to roll their own.
  • Its emphasis on documenting a whole API makes it somewhat cumbersome for producing self-documenting API responses, and would mean we’d need to either mangle it for that, or use some other standard (or roll our own).
  • It treats paths within the API as the identifier for resources, meaning the current path is the canonical identifier for a given resource type. This means (without changing consumer code) the resource always has to live at that path, or that clients always have to follow a redirect to the new location. Compare to Mark Nottingham’s “Home Documents for HTTP APIs”, where the resource identifier is a link relation type (which, I’ll grant, are cumbersome), meaning clients couple to the type of thing they’re expecting to address, not the current server path of that thing. The latter seems more designed with HATEOAS in mind, the former seems… brittle.
  • It is… unclear on versioning, but seems generally in favour. The OpenAPI v3 spec says that info.version is required, and is the version of the OpenAPI document (not the version of OpenAPI being used, or the version of the API itself), but Swagger’s docs say that info.version is the version of the API itself. The schema for OpenAPI v2 goes further, to say that info.version is “A semantic version number of the API.” Given that every version bump to web APIs is a breaking change for all consumers, I’m particularly uncomfortable endorsing that as a way to version web APIs (and am generally uncomfortable with web APIs being versioned).

All of those, to one degree or other, seem to be detrimental to making properly RESTful APIs so, as Paul suggests, I’d say we offer OpenAPI as one option for documenting APIs, but maybe have some pointers for when it may be problematic?

@audreyt

This comment has been minimized.

Copy link

commented Aug 8, 2017

(Cross-posting from PDIS.tw forum, at @edent's request)

Guiding Policy

Taiwan's National Development Council have implemented these measures:

Validation mechanism

Following automated validation of accessibility A+ standards, we encourage agencies to use automated acceptance-test OAS toolkits to validate APIs.

Promotion mechanism

The National Development Council periodically convenes joint IT leadership meetings on national and local levels. We held an "OAS Town Hall" and published the full transcript online.

Before ratification, we also sought advice with local experts, as well with Rufus Pollock from the Open Knowledge foundation (initial meeting, follow-up meeting).

Procurement support

We have included two key Linux Foundation standards, the OAS3 specification as well as open source license manifest (including but not limited to SPDX) into the procurement template for digital services.

We are also amending "Regulations for Selection and Fee Calculation of Technical Services Providers Entrusted by Entities " to legally authorize all IT departments to ask vendors for conformance to OAS at little or zero additional cost.

@garethr

This comment has been minimized.

Copy link

commented Aug 9, 2017

This is purely a documentation standard for APIs

I would be very wary of treating OpenAPI purely as something used to document an API. Doing so brings a lot of complexity but misses out on most of the features in my experience of using and consuming it. Reading some of the original comments it feels like a mismatch exists between folks wanting something like a standard HTML document describing an API for end users, and what OpenAPI is, both of which could be described as "documentation". The reality is OpenAPI is documentation (in a very general sense), which can used to generate HTML (or similar) documentation for end users. For instance the user research purely focuses on the end user docs and ignores other broader meanings of documentation. As a concrete example I'd say things like http://petstore.swagger.io/ are examples of clients using OpenAPI, not OpenAPI itself.)

OpenAPI also only covers a particular type of HTTP based API. What happens if my API can't be described using OpenAPI (it's using GRPC, graphql, different HTTP semantics, etc.). Where does the burden of proof lie when it comes to arguing that this isn't possible in a particular case? Is that understandable to potential API consumers or does the standard exert pressure to do the wrong thing?

It's also worth noting that although the v3 spec has been published, that version isn't in use anywhere to my knowledge yet. And the tooling around the standard which exists for v2 and before doesn't yet exist. Neither of those means it's not the right option, but I would question the answer to the question:

Has the formal specification been used for different implementations by different vendors/suppliers?

Taking the formal specification to be OpenAPI v3 the answer is really No.

I think it's worth very clearly defining the scope for this standard as it has the potential to be widely misused otherwise I fear. It might also be the case the scope ends up so tight that a Government-wide standard doesn't make sense. I think it's also worth waiting on usage and tooling around v3. I have no-doubt that will come, but until it does mandating a standard will see a lot of cycles wasted on building the tools to produce and consume it.

@AlecMulinder

This comment has been minimized.

Copy link

commented Aug 10, 2017

(From SteveMarshall)
...All of those, to one degree or other, seem to be detrimental to making properly RESTful APIs so, as Paul suggests, I’d say we offer OpenAPI as one option for documenting APIs, but maybe have some pointers for when it may be problematic?

I think pointing out where the standard is problematic is a very good suggestion. I also like an earlier suggestion of at least referencing it as a best practice approach in the Service Manual.

I'd favour a stronger endorsement and also like the approach i think initially suggested by @edent of adopting a standard and then influencing its further development. I like very much the comments by @audreyt as they illustrated how standards adoption can be influenced and shaped.

Has there been any benefits analysis undertaken in comparison to RAML?

@BillSwirrl

This comment has been minimized.

Copy link

commented Aug 14, 2017

We've had generally good experiences with OpenAPI, but I'd agree with several other commenters that proposing it as a best practice rather than as a standard is probably more appropriate at this stage.

It's a good way to go for some styles of API, but we could get in a mess trying to define what subset of all APIs are the ones for which OpenAPI should be mandatory.

Pointing to it in the Service Manual, and explaining what aspects of OpenAPI are desirable and why, sounds like a very positive step - and would avoid the risks of accidentally pressuring developers to do the wrong thing in some circumstances.

@edent

This comment has been minimized.

Copy link
Contributor

commented Oct 18, 2017

We had a meeting with Ole Lensma the CTO of SmartBear. Good discussion around some of the topics mentioned here. Will see if we can publish a summary before making our recommendation.

@edent

This comment has been minimized.

Copy link
Contributor

commented Nov 2, 2017

Swagger is being used by the U.S. General Services Administration.

They are looking to update to OpenAPI - see GSA/code-gov-api#126

@Lawrence-G

This comment has been minimized.

Copy link
Contributor

commented Apr 17, 2018

See the Inside GOV.UK blog post - What we learnt from creating API documentation

The GOV.UK team talk about their use of OpenApi version 3 and their intention to feedback into this challenge.

@edent

This comment has been minimized.

Copy link
Contributor

commented Aug 29, 2018

Just had this from the EU's MSP.

Please note the CAMSS Team has finalised the review of the submission form of the Open API Specification v3.0 technical specification submitted by the Netherlands for identification in accordance with Article 13 & 14 of Regulation (EU) No 1025/2012.
https://webgate.ec.europa.eu/fpfis/wikis/display/ICTspecsIdentification/OAS+Submission+form?preview=/293411144/293411151/OAS%20v3.0%20Submission%20form_v1.0.DOC
In accordance with step 1 of the MSP streamlined evaluation process (documentICT/MSP(2018) 014a rev 1) the CAMSS Team will proceed now with the elaboration of a draft evaluation report.

@PeterParslow

This comment has been minimized.

Copy link

commented Aug 29, 2018

Hi Terence,
I have a log on to the EC WebGate, but that link returns Page Not Found. This may be some permission issue (I may not have permission to view that bit) - but could you check the URL you've posted?

@edent

This comment has been minimized.

Copy link
Contributor

commented Aug 30, 2018

@PeterParslow URL is right - but the content has disappeared. I'll try to find out where it has gone.

@edent

This comment has been minimized.

Copy link
Contributor

commented Sep 3, 2018

That link should now work. I've attached the Open API v3 evaluation here as well.
625 OAS v3.0 Submission form_v1.0.DOC.zip

@edent

This comment has been minimized.

Copy link
Contributor

commented Sep 11, 2018

the CAMSS Team has finalised the draft report of the OAS OpenAPI Specification v3.0 technical specification submitted by the Netherlands for identification in accordance with Article 13 & 14 of Regulation (EU) No 1025/2012.
The draft evaluation report has the number ICT/MSP(2018)627: https://circabc.europa.eu/sd/a/d357dbdc-3ad1-46f9-9f79-53d280d06a6c/627%20OAS_3-0%20(OAI)%20CAMSS%20DRAFT%20REPORT.odt
CAMSS team believed that OAS developed by the Open API Initiative (OAI) complies with the requirements for the identification of ICT technical specifications set out by Annex II of Regulation (EU) No. 1025/2012.
In accordance with step 2 of the streamlined evaluation process, MSP members are invited to provide their feedback within three weeks (1st October 2018). One week after the end of the three-week period for feedback, the CAMSS Team will produce the final version of this report that will be sent for advice.
You can find the planning and any further document concerning this process in wiki.
https://webgate.ec.europa.eu/fpfis/wikis/display/ICTspecsIdentification/OAS+Planning

@chris-little

This comment has been minimized.

Copy link

commented Mar 7, 2019

The Met Office is using OpenAPI V3 to define and implement data access services: "DataPoint" and "Weather on the Web". The latter is a global international initiative with US, Europe, etc involvement. International work done via OGC, for later endorsement, we hope, by UN's WMO.
OGC has specified a new version, 3.0, of its Web Feature Service standard, currently out for public comment. Weather on the Web built on this. Further OGC sponsored hackathons/plugfests/codesprints being planned for later in the year for updating other OGC standards such as WMS, WMTS, WCS. Probably one in US and one in Europe. OpenAPI is a given.

I'll update later with some links.

@rb-hmrc

This comment has been minimized.

Copy link

commented Mar 11, 2019

So the latest position from us in HMRC is that we still have moving to support OpenAPI as an aspiration for the API Platform. It's definitely our direction of travel. We have some large pieces of upgrade work starting at the moment that will make our Platform more future proof, but after that we will want to revisit OpenAPI support and examine if it's the right time to add that enhancement. Hopefully the concerns raised by other dept's above in this thread may have been addressed by that point.

The main thing holding us back from doing it now is that we've already invested a lot in making RAML work, so we have many strong user needs higher up our priority list.

@paulhulme

This comment has been minimized.

Copy link

commented Mar 19, 2019

My view from Network Rail is that we have not used OpenAPI yet, but we have made use of swagger for internal APIs.
I expect our future public APIs to continue in this direction, and using OpenAPI will be a good fit. Our current public APIs are mostly raw MQ, not REST.
I think it would be good thing to back OpenAPI as an Open Standard for government.

@jonathanglassman

This comment has been minimized.

Copy link

commented Apr 10, 2019

All

I'm a technical writer within GDS, and am the new challenge owner.

Thank you for your feedback, both historical and recent, on this challenge. I have drafted a proposal to take to the Open Standards Board either in June or later in the year. This proposal is attached below.

Please be advised that this is a first draft, and I would like to invite any and all feedback on this content. This feedback can cover the overall approach, the subject matter covered, whether anything is missing, or anything else.

Please provide your comments by 8 May 2019. If you have any questions, please tag me in your comment and I'll respond to you directly.

Kind regards

Jon Glassman

@jonathanglassman

This comment has been minimized.

Copy link

commented Apr 10, 2019

Draft Proposal for feedback: Recommend OpenAPI3 to describe REST APIs

Introduction

This proposal is to recommend that government departments use the OpenAPI3 specification to describe their REST APIs.

Using OpenAPI3 for REST APIs means that departments would be consistent in the way they describe their APIs. It would make it easier when introducing common tools across government to read, display and update the API reference documentation.

The proposal is not a mandate as OpenAPI 3 may not be the most suitable API specification to use.

User need approach

The user need identified by this proposal is to maximise consistency in and accuracy of API reference documentation across government. Adopting the OpenAPI 3 specification should help to achieve this.

Users in the context of this proposal include government departments who create and maintain APIs, and need accurate API reference documentation. Individual users include but are not limited to developers, service managers, product owners and technical architects.

Achieving the expected benefits

If departments use the OpenAPI3 standard, they would be consistent in the way they describe their APIs. Departments would be able to use OpenAPI3 to auto-generate accurate and up to date API reference documentation irrespective of language. The specification will also enable departments to validate, version, maintain and update this generated documentation.

This could help increase adoption of these APIs across government by reducing time spent by departments gaining familiarity with different architectures. It would free up developer and non-technical resource as they would spend less time trying to understand the API. Departments will also benefit from being able to send test requests to their API endpoints using different methods in the interactive API explorer, as well as use other available tooling.

When OpenAPI 3 may not be suitable

The OpenAPI 3 framework is a powerful tool for working with and describing REST APIs. However, departments must assess if OpenAPI3 is the correct framework to document their APIs.

Firstly, OpenAPI 3 is for REST APIs only, and cannot describe SOAP APIs or APIs that use GRPC or GraphQL. Additionally, OpenAPI 3 covers the majority but not all possible styles of REST APIs.

Currently, OpenAPI 3 has a description of itself located at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema. The OpenAPI 3 machine-readable and verifiable JSON schema is still being finalised. This makes it more difficult to assess and verify if an API complies with the OpenAPI 3 specification. This could potentially lengthen the development time of an API written in OpenAPI 3 as it would be harder to spot and fix bugs and issues during development.

However, other validation tools exist. These assess APIs on non-schema criteria such as the API data and references. Some of these tools are located at https://openapi.tools/. Additionally, it must be noted that a JSON Schema validation does not guarantee compliance, because a JSON schema does not allow for validation of all use cases in the specification.

Departments should also assess what tooling is available for their chosen API specification. There are currently multiple OpenAPI 3 tools that enable users to, for example, validate their API (as mentioned above), integrate their API into web pages, or translate an OpenAPI 3 specification into another specification such as RAML. This tooling is regularly expanding, but is not fully comprehensive yet. Other API specifications also have tooling, for example RAML has multiple testing tools located at https://raml.org/developers/test-your-api. Departments should assess what tooling is most appropriate for their use case.

Other steps to achieving interoperability

This proposal is only concerned with promoting consistent and accurate API reference information across government. This is because the OpenAPI specification only covers reference information such as the API’s endpoints. Fully developed API documentation includes other information such as quick start guides, API keys, running a sample application, rate limits and many other subjects. Government departments should still write the non-reference parts of API documentation. This challenge does not include how government departments write their APIs (for example syntax, response format) or where those APIs live.

@chris-little

This comment has been minimized.

Copy link

commented Apr 17, 2019

@jonathanglassman I welcome this proposal, because the international meteorological community has started to move in this direction with its Weather on the Web API, building on the work for geospatial APIs in OGC and W3C with past and forthcoming hackathons.

I am a little concerned about the use of the term 'REST'. Apart from igniting theological architecture flame wars, we find that the key issue is the 'search pattern' as perceived by the end user rather than whether the API is truly RESTful or not.

@jonathanglassman

This comment has been minimized.

Copy link

commented May 16, 2019

Proposal for submission to the Open Standards Board: Recommend OpenAPI3 to describe RESTful APIs

Introduction

This proposal is to recommend that government departments use the OpenAPI 3 specification to describe their RESTful APIs.

Using OpenAPI 3 for RESTful APIs means that departments would be consistent in the way they describe their APIs. It would make it easier when introducing common tools across government to read, display and update the API reference documentation.

The proposal is not a mandate as OpenAPI 3 may not be the most suitable API specification for all use cases.

User need approach

The user need identified by this proposal is to maximise consistency in and accuracy of API reference documentation across government. Adopting the OpenAPI 3 specification should help to achieve this.

Users in the context of this proposal are government departments who create and maintain APIs, and need accurate API reference documentation. Individual users include but are not limited to developers, service managers, product owners and technical architects.

Achieving the expected benefits

If departments use the OpenAPI 3 standard, they would be consistent in the way they describe their APIs. Departments would be able to use OpenAPI 3 to automatically generate accurate and up to date API reference documentation irrespective of language. The specification will also enable departments to validate, version, maintain and update this generated documentation.

This could help increase adoption of these APIs across government by reducing time spent by departments in understanding different APIs. Departments will also benefit from the OpenAPI 3 tooling. For example, they will be able to send test requests to their API endpoints using different methods in the interactive API explorer.

When OpenAPI 3 may not be suitable

The OpenAPI 3 framework is a powerful tool for working with and describing RESTful APIs. However, departments must assess if OpenAPI 3 is the correct framework to document their APIs.

Firstly, OpenAPI 3 is for RESTful APIs only, and cannot describe SOAP APIs or APIs that use GRPC or GraphQL. Additionally, OpenAPI 3 covers the majority but not all possible styles of RESTful APIs.

Currently, OpenAPI 3 has a description of itself located at https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema. The OpenAPI 3 machine-readable and verifiable JSON schema is still being finalised. This makes it harder to assess and verify if an API complies with the OpenAPI 3 specification. This could potentially lengthen the development time of an API written in OpenAPI 3 as it would be harder to spot and fix bugs and issues during development.

However, other validation tools exist. These assess APIs on non-schema criteria such as the API data and references. Some of these tools are located at https://openapi.tools/. Additionally, it must be noted that a JSON Schema validation does not guarantee compliance, because a JSON schema does not allow for validation of all use cases in the specification.

Departments should also assess what tooling is available for their chosen API specification. There are currently multiple OpenAPI 3 tools that enable users to, for example, validate their API (as mentioned above), integrate their API into web pages, or translate an OpenAPI 3 specification into another specification such as RAML. This tooling is regularly expanding, but is not fully comprehensive yet. Other API specifications also have tooling, for example RAML has multiple testing tools located at https://raml.org/developers/test-your-api. Departments should assess what tooling is most appropriate for their use case.

Other steps to achieving interoperability

This proposal is only concerned with promoting consistent and accurate API reference information across government. This is because the OpenAPI specification only covers reference information such as the API’s endpoints. Fully developed API documentation includes other information such as quick start guides, API keys, running a sample application, rate limits and many other subjects. Government departments should still write the non-reference parts of API documentation. This challenge does not include how government departments write their APIs (for example syntax, response format) or where those APIs live.

@PeterParslow

This comment has been minimized.

Copy link

commented May 17, 2019

For interest - and in support! - OS has agreed internally that our APIs should all have OpenAPI specifications, and we support adopting the current version.

Of course, that doesn't yet mean that we've created OpenAPI specs for all our APIs, but we're working on it!

@anjaneshbabu

This comment has been minimized.

Copy link

commented May 18, 2019

New to the group - would like to support the current process and welcome the proposal.

From where I am standing , the heritage/cultural sector is big on accelerating enablers for media exchange across systems - both internal and external. Particularly encouraged by the multipart file uploader which potentially facilitates the large media files.

@Lawrence-G Lawrence-G added Recommended and removed in progress labels Jun 14, 2019

@Lawrence-G

This comment has been minimized.

Copy link
Contributor

commented Jun 27, 2019

The OpenAPI profile has been published on GOV.UK

In the new recommend page of approved open standards
Thank you, to everybody who contributed to this challenge

@Lawrence-G Lawrence-G closed this Jun 27, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can’t perform that action at this time.