Academy Ruins API v0.4.0

View the updated API docs at https://api.academyruins.com/docs

BREAKING CHANGES

• The /diff/cr/{old}-{new} route has been removed. Instead, the /diff/cr route accepts up to two query parameters, old and new. Omitting both will result in the existing behavior of /diff/cr in returning the latest CR diff, but supplying either one or both will result in returning the result between those set codes (if it exists).
• The rules changes inside the CR diff response have had their ruleNum property renamed to ruleNumber to make them consistent with the rest of the API.
• The nav property of a CR diff response now contains only two string (or null) properties, prevSourceCode and nextDestCode, that reference surrounding diffs. This property has also been made entirely optional, appearing only if the nav query parameter has been set to true. In addition, the keys sourceCode and destCode were added directly to the diff object.

New Routes

• /cr/toc/ returns a parsed table of contents for the current CR.
• /cr/trace/{rule} returns the full history of a given rule in the CR.

Other API Updates

• The CR diff response now includes a moved array detailing which rules changed numbers in the diff.
• Rate limiting has been imposed on the API.
• The /cr/keywords response now correctly separates "linked" keywords (such as "Daybound and Nightbound") into two separate entries.
• Various API documentation improvements
• /swagger has been added as an alternative to /docs for those who prefer Swagger UI documentation.

Commentary

I think this is a good time to reflect on the approach this project takes with regards to breaking changes. Firstly, I have to say that the project follows SemVer, and we are currently still in the version zero stage of development, which means API changes are allowed. In a sense, the rules give me blanket permission to do what I want until 1.0. This helps develop the site faster and allows us to not get stuck with our initial mistakes forever.

That said, I also want the API to be useful (and used), and overly aggressive changes are counter-productive to that goal. No one wants to rely on something that may suddenly change under their feet at any moment. So while I'm able to make breaking changes, I try to be responsible with when and where I make them. There are several factors to account for when considering a breaking change:

• How significant is the change?
• How necessary is the change?
• How many people rely on the changed behavior?
• How much will not changing impact future development?

When applying these considerations to the latest CR diff updates, I came to the conclusion that while they aren't the most necessary, they also aren't that hard to adjust for and (to my knowledge) no one really uses those routes anyway, so cleaning up the API took precedence over backwards compatibility.

To contrast that with a situation where a change isn't worth doing, if I had to start from scratch, I might rearrange the API to be more RESTful. /cr/examples/{rule} could become /cr/{rule}/examples, for example. However, I know people are using those routes, and the change would be for only a very marginal benefit, so the current design stays as-is. The /cr namespace in general can be considered pretty stable for those reasons.

As a final thought, I want to say that breaking changes should become less and less expected, as the API gets more refined with each release. Of course, one can't speak of issues not yet found, but at the moment I know of no routes that would need breaking in future releases. Lastly, if you're using the API for your own #thing, get in touch! Not only will it help me with these determinations, I love hearing about cool things people are coming up with.

Full Changelog: v0.3.0...v0.4.0