151–160 of 192 posts
Do any of these API guides have good guidance around batch endpoints like handling a PATCH on multiple resources as a single request?
Earlier quoted context omitted.
> mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. That also rules out using any HTTP method other than GET. The browser address bar doesn't seem relevant here, and if it were, then it would rule out the vast majority of APIs. Versioning through the URL breaks interoperability of clients using different protocol versions. If a cli…
I suspect that we are designing for different clientele. I'm currently in charge of a pretty classic, GET things out, and POST things in API. If my API supports that some non-IT office guy can get his daily report through the browser, and the API at the same time has the power and flexibility needed for someone with IT skills to do more then I've won. Both me and my users gain by me taking extra steps to make it as a…
Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords?
Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time. I don't think I've ever come across non-IT office guys that have more complex versioning requirements than that.
> I also fail to see how versioning through urls break anything, except if the newer client no longer has support for v1.
Here's an example:
Client A (using version 2), talking to Client B (using version 1):
> Here is a friend suggestion for person https://example.com/v2/people/foo
Client B:
> Okay, I'll add them to my contacts. My contact list is now:
https://example.com/v1/people/foo
https://example.com/v2/people/foo (error: cannot parse)
Client A (using version 2), talking to Client B (using version 1):
> Here is a friend suggestion for person https://example.com/people/foo
Client B:
> Hey, I already know that guy!
Once you break the identity part of URIs, you start getting a tonne of these awkward problems to work around. URIs are meant to be the primary keys of the web, and you're going against the grain of the medium when you break that.
To put it another way, imagine if websites had to change every page URI from /html4/ to /html5/ when they switched versions. That's a whole lot of work and breaking things for no reason. I'd rather follow how the web was designed to work and not create so much extra work.
I would like to add Microsoft's API Guidelines [1] here, which is also a well written document and can be helpful to anyone designing an API. [1]: https://github.com/Microsoft/api-guidelines/blob/master/Guid...
It's interesting that both of these guidelines kind of reject HATEOAS by mandating explicit versioning. It seems that HATEOAS was never really a thing. It's just too complicated to implement in practice. In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.
...HATEOS, IDGAF if //api.me.com/article/list uses 404 to mean there are zero articles returned from an otherwise valid resource.
Just yesterday, I asked a back-ender to put the total_pages, page_limit, and current_page on their endpoint.
BE: But you should be able to use my "self", "next", "prev" links?
FE: Well the thing is, I want to generate and render links for every page
BE: Oh, I see...
Earlier quoted context omitted.
I suspect that we are designing for different clientele. I'm currently in charge of a pretty classic, GET things out, and POST things in API. If my API supports that some non-IT office guy can get his daily report through the browser, and the API at the same time has the power and flexibility needed for someone with IT skills to do more then I've won. Both me and my users gain by me taking extra steps to make it as a…
> If my API supports that some non-IT office guy can get his daily report through the browser Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords? Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific…
Basic auth (over https only) actually, I'm even advocating it. We support expirable tokens as well.
>> requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time
The only way for me to go would be option 2: requests without a specific version get version 1. Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations.
>> URIs are meant to be the primary keys of the web, and you're going against the grain of the medium when you break that.
In that context your example makes sense, I just don't see that as realistic problem. In real life URI aren't as static as we pretend. How many companies would make sure the resource urls are still valid after changing the company and domain name?
The real identifier in your case is "foo" and "people" is the type. Accepting that sets you free to do versioning as you please and to save 90% characters in all ids :)
In the end we should design apis for our users, not for our selves. My clients are always non-IT departments, often in enterprisy environments, and if they can get 2-4 hours allocated from IT in the next 6 months to do some API integration, they are lucky. So I design my api for maximum simplicity, and maximum longevity of the using scripts, because if I wanted to make a breaking change, I'd have to wait 6 months before all customers could be expected to have transitioned.
Most of my api users couldn't tell you what a mimetype is btw., but a v2 in the url would make complete sense.
I get where you're coming from, on our latest api version I started out wanting to do full HATEOAS (Bought and read this great book http://www.designinghypermediaapis.com/), but in the end I had too much trouble getting my test customers migrated, so I had to scale back on the desgin goals. Scaling back to what worked for everybody was very informative and the api is now, imo, the better for it.
If I need to bump the vesion it'll be with a vx in the url. An id is a simple non-globally unique thing, that you use to build a url etc.
Earlier quoted context omitted.
I suspect that we are designing for different clientele. I'm currently in charge of a pretty classic, GET things out, and POST things in API. If my API supports that some non-IT office guy can get his daily report through the browser, and the API at the same time has the power and flexibility needed for someone with IT skills to do more then I've won. Both me and my users gain by me taking extra steps to make it as a…
> If my API supports that some non-IT office guy can get his daily report through the browser Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords? Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific…
As for auth a simple token as Github does is enough, and github lets you use it as a header or a get param.
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. The exact opposite of what we should want for API.
Earlier quoted context omitted.
> What they describe is not REST. [...] a strict requirement of the REST architectural style. [...] You have a word "REST" for which you are apparently granted access to Plato's "true" definitions, which enables you to tell me that REST requires hyperlinks, but not naming conventions or HTTP verbs. I reject your definition. Go ahead and use that word "REST" however you like. I will continue using it to describe what…
I am not the authority on what REST is. That would be Roy Fielding, who has explicitly stated that hypermedia is a requirement[1]. So go ahead and tell Mr. Fielding that his definition of REST is incorrect. I am well aware that REST no longer means what it originally described, which is why I think it should go by another term that is not burdened by being a marketing buzzword. [1]: http://roy.gbiv.com/untangled/2008…
Earlier quoted context omitted.
> If my API supports that some non-IT office guy can get his daily report through the browser Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords? Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific…
>> I guess you're using something like HTTP digest auth with usernames and passwords? Basic auth (over https only) actually, I'm even advocating it. We support expirable tokens as well. >> requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time The only way for…
"Some other people might write code that does things incorrectly and then their software might break" is something you can say about any API style, it's nothing special to media type versioning. If many of your customers are writing code that integrates with your API incorrectly, you don't have an API design problem, you have a poor communication problem, and that's going to hurt you in all kinds of ways.
> In real life URI aren't as static as we pretend.
They are static if you don't deliberately break them; I'm just pointing out some of the consequences if you choose to.
> How many companies would make sure the resource urls are still valid after changing the company and domain name?
Companies are laser focused on this if they rebrand. Companies love their search rankings. But how common is it to rebrand? Optimise for the common case, not the uncommon ones.
> The real identifier in your case is "foo" and "people" is the type.
You're turning URIs from an opaque identifier clients can use as-is to a compound structure that clients have to parse, manipulate, and (re)generate. You're putting more logic on the client, and thus giving client developers more rope to hang themselves with immediately after saying they can't be trusted to get things right.
This is not designing for maximum simplicity. Designing for maximum simplicity is to have an API that says "here's a link; follow it", not an API that says "here's an ID, generate a URI from it according to these rules we set out in our documentation, that are different for every type of resource". The latter is more work and more error prone.
Earlier quoted context omitted.
It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…
Just guessing, if you had an API for creating documents for example, and you POST a request to /docs/ you'd get back not an just a single ID but a URL to /docs/ . So then the client can operate on that resource and not have to compose it. It can also be browse-able with a regular browser. If you visit it say with Firefox and go to .../api/ and the browser tells the backend it accepts text/html back, the service would…
Earlier quoted context omitted.
> If my API supports that some non-IT office guy can get his daily report through the browser Most APIs I work with wouldn't work this way even for read-only access because of authentication requirements. I guess you're using something like HTTP digest auth with usernames and passwords? Even so, that still works for your use case as long as your users are happy with a default version. e.g. requests without a specific…
When you say client do you mean how humans passing around URLs? 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. Even under some sort of weird direct connection situation where the server wouldn't be generating the paths using the URLs as GUIDs seems like a really strange decision. As for auth a simple token as Githu…
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?
Earlier quoted context omitted.
Just guessing, if you had an API for creating documents for example, and you POST a request to /docs/ you'd get back not an just a single ID but a URL to /docs/ . So then the client can operate on that resource and not have to compose it. It can also be browse-able with a regular browser. If you visit it say with Firefox and go to .../api/ and the browser tells the backend it accepts text/html back, the service would…
If you get back an URL to the document instead of the ID, then whenever you need to refer to that document, you need the whole URL. That means that it can't change, which I thought was one of the arguments for using HATEOAS, that you don't need to hardcode the URLs, and can "evolve" the API without breaking clients.