Joan James

Biography

After receiving her BS in Math and Computer Science, Joan started her career as a Software Engineer at Motorola Cellular Infrastructure Division where she worked for twenty years gaining experience in all phases of the software development life cycle. After a gap in her career for raising her son, Joan returned to full time work as a Technical Writer at Motorola Solutions, GE Healthcare and finally Zebra Technologies Enterprise Software. She enjoys working on pan-Zebra architecture and process initiatives related to API Management. In her free time, Joan teaches and plays piano.

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.