Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Aside from documentation, how do you judge if an API is good?


= Design characteristics =

1. Simple, distinct concepts with unambiguous names.

2. Semantics are clear, following conventions as appropriate.

3. Minimize surface area without reducing functionality.

4. Clarity and specificity of ErrorCodes and messages.

= Operational characteristics =

1. Extremely low level of 500s.

2. Low call latencies.

3. The API does what it says it does.

4. Consistency is (nearly) always within its documented SLA.

5. Do not make backwards incompatible changes.

= Social characteristics =

1. Docs are correct, up-to-date, complete, specific, and unambiguous.

2. Clearly communicate service outages and resolution timelines.

3. Seek feedback on evolving the APIs.


For me it’s about consistency, in order of importance:

1. self-consistency: Every entity and operation has exactly one name, a given verb always implies the same operation, paths are always constructed the same manner

2. consistency with industry norms (eg REST)




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: