The document outlines key elements for creating an effective API reference, emphasizing the importance of easy access to documentation, organized use case examples, and detailed descriptions of API functionalities. It highlights the need for proper error handling, including clear descriptions of HTTP status codes and relevant error response examples. The aim is to improve developer experience by providing comprehensive resources and guidance on using the API.

1. AAVISTA OY
Merja Kajava
@mkajava
APIOPS MEETUP
ELEMENTS OF A GREAT
API REFERENCE
17.3.2020

2. WHERETO FINDTHE API?
PROVIDE AN EASY ACCESS TO API REFERENCE

3. YOU DO NEEDTHE DEVELOPER SITE
EASY ACCESS TO API REFERENCE
PDFdeveloper.mysite.com

4. 4
Detailed
documentation
API REFERENCE
Developer support
SUPPORT
DEVELOPER SITE
Getting started
Concepts
Examples
API
DOCUMENTATION
Experiment with API
SANDBOX
Changes to API and
documentation
RELEASE NOTES
Uptime for API
UPTIME STATUS

5. WHERE IS THE API REFERENCE FOR MY USE CASE?

6. 6
API REFERENCE ORGANIZED BY USE CASE

7. GOOD EXAMPLES NEEDED

8. Include also proper decriptions. Is
country_code here ‘US’ or ‘USA’.
DESCRIBE THE FIELD PURPOSE
‘Foo’ or ‘null’ or ‘string’ is not a
helpful example.
USE PROPER EXAMPLES
WRITING GOOD API EXAMPLES IS NOT EASY

9. HOWTO DEAL WITH ERRORS

10. Describe HTTP status codes
Identify error types
HOW TO DEAL WITH ERRORS?

11. PROVIDE EXAMPLES FOR ERROR RESPONSES

12. KEY ELEMENTS
Provide the developer site with easy to find API
reference
Describe the API properly
Use good example values
Describe error handling
ELEMENTS OF A GREAT API REFERENCE

13. THE DEVIL ALWAYS IS INTHE
DETAILS

14. The Data Refinery Company
MERJA KAJAVA
@mkajava
https://www.linkedin.com/in/merjakajava