Version number

[smythp]

Think it will prevent some trouble if you add a version number to your URIs:

/api/v0.1/subjects/detectivefiction

Interesting discussion here, though some of it is probably overkill for this:

https://stackoverflow.com/questions/389169/best-practices-for-api-versioning

[JonathanReeve]

I thought about this, but I ended up deciding that it just looks friendlier without the version number there, for now. If I make it to 2.0, and anyone at all is using this thing, then I might do something like /api2/.

[smythp]

OK. Only issue is that if I, or someone else, makes a script using this version, and then you update it, you're stuck either keeping all the endpoints the same or breaking the scripts. As an API designer you're making an implicit contract with the user, if you change stuff then people will be hesitant to build anything with it.

You might consider supporting an optional query parameter that allows the old version. Alternatively you could call all of this a beta and just say it's not ready for prime time yet. Since you have to support old versions once you have them that might be the way to go. But I do feel like an API is not like a website, if people are building stuff then you have to trust that stuff won't break.