1. 41
  1.  

  2. 10

    Good list. I would also add:

    • Indicate what data is nullable / optional in a response.
    • Indicate the format / type of data in a response.
    1. 6

      Another one: if you have an API that provides historical metrics for something, allow the user to query the start and end date range for those metrics. Otherwise, people may hit your API for metrics that don’t exist for that date range.

      1. 6

        Have a good strategy for evolution, deprecation, and backward and forward (in)compatibility.

        1. 4

          @eduardo, edmz.org’s certificate expired.

          1. 3

            To clarify, this article seems to be mostly about APIs documentation. (And quite interesting at that.)

            As to APIs themselves, I recently learned about https://aip.dev, and found it an extremely valuable set of good practices for designing APIs. Based on my experience, I see them as preemptively providing solutions for many problems you won’t even know you have until it’s too late. Highly recommended!