Re:API Design Guide
by JimDabell on Thursday February 23, 2017 @03:00AM
(#13712392)
> When you say client do you mean how humans passing around URLs?
No, I mean API clients.
> I can't come up with any reason why two client applications would be sharing full API URLs directly with each other, that seems like very poor design.
URIs are the primary key for resources on the web. If two clients want to talk about the same resources, then they need to agree on an identifier, and that's exactly what URIs are designed for.
> As for auth a simple token as Github does is enough
The design criteria in this example is "Can be typed into a browser address bar by a non-technical person". I don't think auth tokens meet that criteria.
> Your choice of HTML 4/HTML 5 for comparison seems aptly poor. Instead of clear versioning, old browsers get HTML they don't understand and fail unexpected, unpredictable and ungratefully ways.
You're conflating two different things there; how versions are communicated, and the compatibility strategy. Whether or not HTML did a good job of maintaining compatibility between different versions, do you agree that changing the URI of every web page on the web to communicate when they change HTML versions is a bad approach?
No, I mean API clients.
> I can't come up with any reason why two client applications would be sharing full API URLs directly with each other, that seems like very poor design.
URIs are the primary key for resources on the web. If two clients want to talk about the same resources, then they need to agree on an identifier, and that's exactly what URIs are designed for.
> As for auth a simple token as Github does is enough
The design criteria in this example is "Can be typed into a browser address bar by a non-technical person". I don't think auth tokens meet that criteria.
> Your choice of HTML 4/HTML 5 for comparison seems aptly poor. Instead of clear versioning, old browsers get HTML they don't understand and fail unexpected, unpredictable and ungratefully ways.
You're conflating two different things there; how versions are communicated, and the compatibility strategy. Whether or not HTML did a good job of maintaining compatibility between different versions, do you agree that changing the URI of every web page on the web to communicate when they change HTML versions is a bad approach?