API Documentation.pptx
- 2. Your best quote that reflects your approach… “It’s one small step for man, one giant leap for mankind.” - NEIL ARMSTRONG
- 3. What is API API stands for application programming interface, which is a set of definitions and protocols for building and integrating application software.
- 4. Generating API documentation ◦ The API Builder provides one place to view, create, and manage all of your API's documentation
- 5. Sending your first request •Send a request to an endpoint, retrieve data from a data source, or test an API's functionality. •Create a new request and select Send, and the API response appears right inside Postman.
- 6. API requests defined •APIs provide a structured way for one application to access the capabilities of another application •A client application (like a mobile app) sends a request to the server, and after the request processes the server returns a response to the client. •A request includes the URL of the API endpoint and an HTTP request method. The method indicates the action you want the API to perform. • GET retrieves data from an API. • POST sends new data to an API. • PATCH and PUT update existing data. • DELETE removes existing data.
- 7. Sending a Request •Select + in the workbench to open a new tab •Enter postman-echo.com/get for the request URL. •Select Send. • Postman displays the response data sent from the server in the lower pane.
- 9. What Happend •Postman sent a GET request to the Postman Echo API server located at postman-echo.com. •The API server received the request, processed it, and returned a response to Postman. •Postman received the response and displayed it in the Response pane. •You used Postman to send an API request and got a response from the API server.
- 12. • What is API Documentation • What are the benefits from using APIs? • How does an API Work? • Who and How creates the API and the API Documentation • Which tools to use to try an API or to automatically generate API Documentation
- 13. What is an API? APIs stands for an application programming interface The API allows two different software applications to interact with each other. Using the API, these applications can exchange data in a reliable way. PUT A IMAGE of API
- 14. Benefits from using an API? By using an API, the applications can gain immediate access to software modules and functionality that is already developed by another application. This way you can leverage and reuse existing functionality from another application in the context of your own app, allows you to offer more functionality to your customers.
- 15. How does an API Work? When using an API, an applications first sends a request to use the functionality. The receiving application performs all the work and in the end, returns a response.
- 16. Who creates API and API Documentation? Usually, you must be the developer who created the API to be able to explain how the API works. Usually, the technical writers are not developers, but are a part of the team of developers who creates the API. As a consequence as a technical writer would focus on writing documentation about using the API.
- 17. What is an API Documentation? • What the API can do for me? What functionality does it offer and what work can it do for my application? It’s a piece of documentation. Once the API is developed and the writer doesn’t know what is the API being developed and what is the function of it. • How to connect to the API? • How to authenticate myself, once connected to the API? • What are the types of requests I can send to this API? What are their parameters? • What are the types of responses I can expect to receive once the API requests is being processed? What will be the result I can expect to get in the end?
- 18. Types of APIs • “Standard” API- direct connection protocol • Web API- transfers the request and response via HTTP ( Hypertext Transfer Protocol) on the WEB
- 19. Who reads API Documentation? Documentation about the API is what I call “developers documentation” – It is for a target audience of Software developers. To properly use the API, developers need to know the technical details of API. Note, that the end users would not need API documentation; for them you provide end user guides where you aim to reduce technical details and implementation information. Examples of API Documentation https://stripe.com/docs/api Stripe is cited frequently as one the best examples of a high-quality API documentation SAP’s API documentation sample: https://api.sap.com/api/storage_manager/resource
- 20. User Swagger tool to auto create API Documenation Link: https://swagger.io/solutions/api-documentation/
- 21. API Documentation –Framework Where to start- First step is to automatically generate documentation from the API design annotations themselves. What is a tech writer to do next ? Write the rest of the documentation! What is the information you must provide in your API documentation to complement the automatically generated one make it a great user experience: • How to access the API? • What types of requests the API accepts? • What types of responses the API returns?