SARAH GIDEON 10th December 2016 BEST PRACTICES OF API DOCUMENTATION USING SWAGGER © 2016, STC India chapter SARAH GIDEON 10th December 2016

aGENDA This presentation will demonstrate the usage of an API representing tool – Swagger to build on existing documentation of APIs. © 2016, STC India chapter

Key Objectives How to execute APIs using swagger Key Objectives How to execute APIs using swagger. Testing and updating live content for developers. Do’s and Don’ts of API documentation. Industry best practices and globally adopted standards.

API>>>> APPLICATION PROGRAMMING INTERFACE A set of functi ons and proced ures that allow the creation of applicatio ns which access the features or data of an operating system, application, or other service. In computer programming, an application programming interface (API) is a set of subroutine definitions, protocols, and tools for building software and applications. API>>>> APPLICATION PROGRAMMING INTERFACE

>>How does an API work? >>APIs are a set of subroutine definitions, protocols and tools that build a software. >>How does an API work? APPLICATIONS API [Application Programming Interface] APPLICATIONS DATA

The API Economy APIs drive digital transformation APIs are treated as strategic assets APIs are becoming software products IoT exposes need for focus on security

What are the tools that Represent APIs? SWAGGER README.IO JEKYLL API BLUEPRINT RAML MIREDOT

What should we know about it as Technical Writers? APIs are the communication channel of the connected world. API Developers need help integrating their App to other Apps. API Documentation is for - Developers. They are our audience. They build Web Applications, Ios and Adroid Software, using the documentation that we provide.

BEST PRACTICES OF DOCUMENTING APIs

Resource Descriptions Parameters [Limitations with these parameters] Elements of an API Endpoint Definitions Methods Resource Descriptions Parameters [Limitations with these parameters] Sample Requests Sample Responses Sample and Error Code

How to Represent APIs Grouping and Space Creation API Scenario Page Title = API call Tabular Format Using Code Blocks Parse Format

Exposing login credentials Documenting complete sample payloads. ……Documenting APIs Identifying and Documenting for select Data Repositories or platform products Exposing login credentials Documenting complete sample payloads. Limitations using Parameters

API Documentation Analysis Facebook Twitter Google Maps Uber

Comparative Analysis of API Documentation across the following applications API Elements Facebook Twitter Google Maps Uber Endpoint Definitions Method API Call contains the Method (But it is not specifically mentioned) Resource Description / Header Parameters (Optional & Mandatory) Sample Requests and Response Only Response Codes

Thank you! © 2016, STC India chapter