How the OpenAPI Specification Led to Better REST API Design | Joan James | API The Docs Virtual 2020

"How the Open API Specification Led to Better REST API Design" by Joan James, API The Docs Virtual 2020

Talk Description:
"In my role as API Technical Writer at Zebra Technologies, I lead a team of developers and architects to create REST API Design Guidelines for the API developer community. This presentation will cover REST API Design Best Practices such as resource naming, parameter naming, popular header values, and error response payload consistency.

API Documentation instructs the developer-partner audience with overviews, use cases, and descriptions of every call and parameter. It should be easy to read, enjoyable to interact with and result in developer-partner success. Language, grammar, punctuation, formatting, consistency and technical references are important to technical writers. But what happens when the API design gets in the way of good documentation? Is a parameter named ‘t’ informative to the developer-partner? What about inconsistent use of hyphens and underscores?

The Open API Specification enables an API Design First philosophy where we can apply Best Practice standards on the API design and documentation. Numerous linters are available for the Open API spec which validate servers, paths, parameters, request and response bodies and more. With a good API Design methodology and a custom linter, your organization can provide APIs that suggest expected behavior and a satisfying user experience."

---

API the Docs is an event for tech writers, API developers, product owners and developer evangelists who embrace documentation as a crucial aspect of a great developer experience. The conference is a great opportunity to share and discuss the latest best practices, strategies and new trends relevant to API documentation and developer portals.

[TerenceWight]

Hi. You mention at around 20:45 that it's not a good idea to use a response body with a GET request. What would you do if the data to be sent as parameters to the REST API was too large to pass in the query string? We have this situation with a handful of requests and we use a POST instead, but it is an inconsistent use of the POST HTTP verb because we are really just GETting data, not updating it. The query string has a character limit of 2K which makes a GET with request body seem like the only way out.