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

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

3. 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.

4. 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

5. >>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

6. 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

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

8. 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.

9. BEST PRACTICES OF DOCUMENTING APIs

10. 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

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

18. 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

19. API Documentation Analysis
Facebook Twitter Google Maps Uber

28. 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

29. Thank you!
© 2016, STC India chapter