HNHacker News
TopNewBestAskShowJobs

mpnally

2 karma · joined May 13, 2019

submissionscomments
mpnally··on Use links not keys to represent relationships in APIs
It required some discipline. I had to catch myself several times. The reason I avoided those terms is that I wanted readers to focus on one simple idea and not get distracted by all the baggage those terms bring with them. You can see by the comments that I wasn't totally successful.
mpnally··on Use links not keys to represent relationships in APIs
In the style of JSON I like to use, and whih GitHub and Google Drive use, the relationship name is given by the JSON name. So if you see 'owner: /person/12345', then 'owner' is the relationship name. There are other JSON styles for expressing the relationship name — the blog post mentions some of them. You might quibble about whether these names are the names of the relationship, or just names of one end of the relationship.
mpnally··on Use links not keys to represent relationships in APIs
I have implemented many APIs in this style, both read and write. Depending on the design of the storage layer, the server may or may not have to parse ids out of URLs. The client never has to; for the client, the URL is the only Id.
mpnally··on Use links not keys to represent relationships in APIs
One simple strategy is not to change your approach to storage of IDs, which can continue to be "simple" keys. If you use that strategy, the only change from a "conventional" application is that the server is doing all the URL<->simpleId conversions instead of pushing that responsibility onto the client. Another good strategy is to store Ids in the form that the URI spec calls "path-absolute" URIs — basically you lop off the scheme and authority. This strategy works well, but may require a bit more care, and may cause problems if you have to integrate with other tables that have a different approach to keys.
mpnally··on Use links not keys to represent relationships in APIs
If some parts of your API used database keys as identifiers and other parts used URLs, then I can see that could be confusing. All one or all the other would probably be better.
mpnally··on Use links not keys to represent relationships in APIs
Your suggestion for using content_type for versioning makes sense if you believe it makes sense to invent a new media type for every entity in your domain model (customer, invoice, ...). I don't think this is a good practice. I always stick to the standard media types (application/json, text/html, ...)
mpnally··on Use links not keys to represent relationships in APIs
If you follow this model consistently, the client never needs the concept of an "actual id". For the client, there is only one Id — the URL. The client can use it anywhere that in other models they might need to use an "actual id"
mpnally··on Use links not keys to represent relationships in APIs
In the model where identifiers are URLs, your example would most naturally look like this: /invoices?customer=/cust/123456. /cust/123456 is an opaque identifier for the client. Since /invoices?... itself is a URL and therefore a URI, it must be the identifier for something—it is the URL of a query result. You can also have a property of a customer that looks like 'invoices: <url>', in which case that URL is opaque. Regarding your second point, it is true that clients still need to understand the entities of the problem domain, but this is still simpler than having to learn the entities and also learn the URL templates that are used to access them, which is the alternative.
mpnally··on Use links not keys to represent relationships in APIs
JSON works this way too. This deals with how to deal with the evolution of the data associated with an entity, it does concern the identifiers.
mpnally··on Use links not keys to represent relationships in APIs
Saying that URLs are not idiomatic with RPC or GraphQL is really just saying that most people aren't used to this way of thinking. Specifically, they are not used to is treating URLs as identifiers. Most programmers and API designers think of URLs as being a way of encoding remote procedure calls, with identifiers being parameters to the call that must be embedded inside the URL. The point of the blog was to try to explain why a minority of people like to use a different model where the URLs _are_ the identifiers.
mpnally··on Use links not keys to represent relationships in APIs
You don't have to parse entity IDs our of URLs — the URL already is an entity ID, and from the client's perspecitive, it doesn't have any sub-parts that can be parsed out, except those defined in the URI spec (scheme, authority)
mpnally··on Use links not keys to represent relationships in APIs
I don't think Fielding meant to say that you cannot bookmark a URL, which is what your interpretation would imply. He was only commenting on how you find the URL in the first place to bookmark it.
mpnally··on Use links not keys to represent relationships in APIs
Cache timeout limits generally apply to the data retrieved for a URL, not the URL. If you know that your clients will never "bookmark" or in any way store URLs, then you can change them. The same rule applies for all identifiers, not just URLs