SARAH GIDEON 10 th December 2016 2016 STC India chapter BEST PRACTICES OF API DOCUMENTATION USING SWAGGER aGENDA This presentation will demonstrate the usage of an API representing tool Swagger to build on existing documentation of APIs ID: 765580
Download Presentation The PPT/PDF document "SARAH GIDEON 10 th" is the property of its rightful owner. Permission is granted to download and print the materials on this web site for personal, non-commercial use only, and to display it on your personal computer provided you do not modify the materials and that you retain all copyright notices contained in the materials. By downloading content from our website, you accept the terms of this agreement.
SARAH GIDEON 10th December 2016 © 2016, STC India chapter BEST PRACTICES OF API DOCUMENTATION USING SWAGGER
aGENDA This presentation will demonstrate the usage of an API representing tool – Swagger to build on existing documentation of APIs. © 2016, STC India chapter 2
Key ObjectivesHow 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 functions and procedures that allow the creation of applications 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.
APPLICATIONS API [Application Programming Interface] APPLICATIONS DATA >>APIs are a set of subroutine definitions, protocols and tools that build a software. >>How does an API work?
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 API s ? 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
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
……Documenting APIsIdentifying 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 chapter29