I've worked with APIs that used IDs to communicate state. While that works, IDs are a poor abstraction to communicate possibilities. IDs are good for structur

I've worked with APIs that used IDs to communicate state. While that works, IDs are a poor abstraction to communicate possibilities. IDs are good for structuring relations and composition (hasMany, belongsTo etc) whereas links indicate actions. An ID says: "there is a thing somewhere". A link says "you can do somthing there". My example of "getting an invoice" is a bad one for this, because a GET is where IDs and links overlap. "There is an invoice somewhere" is almost the same as "there is an invoice there". It becomes more apparent when creating things. No ID can communicate that a client may add a payment. Or can delete a tag. Or can move an item. Links can do that. So, I find that links are better abstractions because they cover all these cases whereas IDs cover only a subset.