GitHub Pages website: https://kenneth-lau.github.io/udemy-api-doc3
For more information on this course, see The Art of API Documentation at Udemy.
- Overview
- Why
- Requirements
- Key concepts
- Workflow
- Visual information, diagrams,
- Getting started
- Lead people through a simple task
- WEB APIs
- registration
- get an app key
- authorization
- doing something simple
- Platform APIs
- Downloading SDK
- Setting up IDE
- doing something simple
- Tutorials
- common tasks
- step-by-step
- screenshots
- start with basic tasks then advanced
- Sample code
- short, simple programs that work
- able to copy and modify
- common tasks
- well commented
- different from production code
- Important because
- What can the API do?
- What is required to use the API?
- Is it well-designed?
- High-level view
- Explain why?
- describe key features
- provide a few use cases
- Requirements
- WEB APIs
- usually not required
- Platform APIs
- programming languages supported?
- OS, SDKs, IDEs required?
- versions required?
- WEB APIs
- Key concepts
- write a paragraph or two for each concept. what does the API do?
- Architecture
- diagram
- explain major pieces and how they fit together
- Workflow
- describe order of tasks
- order of API calls
- Diagrams
- architecture diagram
- workflow diagram
- Why
- to make the API less intimidating
- Hello world
- simplest program that demonstrates feature of API
- TTHW - time to hello world
- Structure
- step-by-step instructions
- include lots of screenshots
- Web APIs
- registration
- getting app key
- making one or two HTTP requests
- Platform APIs
- how to download SDK
- setting up IDE
- creating an app that does a simple task
- Purpose
- hold hands and lead developers through common tasks
- Cover common tasks
- Same structure as getting started
- Sample HTTP requests or sample code
- Screenshots
- Web APIs
- not many screenshots needed
- Platform APIs
- not many screenshots
- maybe for IDE or something visual
- How many?
- 3-5 usually
- Guidelines
- prioritize languages
- relevant information grouped together
- clarity over efficiency
- Importance
- developers want sample code
- can copy, paste, and modify
- Web APIs
- can be called from any language
- Platform APIs
- in the language of the SDK
- Illustrate workflow
- show a series of API calls
- Use hard-coded values
- Never use hard-coded values in production code
- group relevant information together means use hard-coded values in sample code
- exception: app keys and access tokens
- plenty of comments
- they are critical
- every class, function, or method should have at least one line
- Meaningful names
- variable, class, and member names should be clear
- clarity is more important than efficiency (in sample code)
- long, unwieldy names are fine: they add clarity
- never use meaningless names like "foo"
- Object oriented programming
- does not "group relevant information together"
- GUI Tools
- Postman
- command line tools
- easy to include in Documentation
- cURL or "curl"
curl --help
orcurl -h
- flags
- -X, --request (indicates method)
- -H, --header
- -d, --data