- You should communicate clearly about the number of items and pages developers can expect from each endpoint so that developers don’t make assumptions about it.
- Your spec should clearly state the size constraint for each response developers should keep in mind while coding.
- Your spec must set a performance standard and stick with it because developers code for their applications using your APIs after considering how fast/slow your APIs return requests.
- Cover authorization extensively in your specs. Encourage the use of refresh tokens throughout your documentation.
Full post here, 5 mins read