Academy Ruins API v0.5.1

What's Changed

A few oversights in the 0.5.0 migration meant the released Docker container wasn't bootable and some internal routes produced incorrect responses. Those issues have been addressed.

Full Changelog: v0.5.0...v0.5.1

Academy Ruins API v0.5.0

API Updates

The routes deprecated in version 0.2.0 were removed from the API.

Internal Changes

• The project was majorly restructured, which I hope will improve future readability and extensibility.
• A new Github CD pipeline was created for automatically packaging and uploading built Docker containers for every release.
• The CR diff database schema was reworked, resulting in much improved performance of /cr/trace queries.

Full Changelog: v0.4.0...v0.5.0

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

Academy Ruins API v0.3.0

BREAKING CHANGES

• /diff/cr/latest has been moved to /diff/cr
• All API responses have been converted to use camelCase dictionary keys. This was done to make the rest of the API behave more similarly to routes inside the /cr namespace, which were already using this case. The only existing documented route affected by this change is /diff/cr/{old}-{new}. Query parameters are unaffected by the change.

Other API Updates

• MTR support is here! Routes for the parsed MTR, individual MTR sections, and MTR diffs were added. Their usage is more thoroughly documented in the API docs.
• In the event of an internal server error, a valid JSON error response is now returned instead of a plain text document.

Internal Changes

• A large code reformatting was done using a combination of black, flake8, and isort.
• A CI pipeline with the aforementioned tools has been created to check incoming pull requests.
• Most pydantic models were refactored to use @dataclass instead of descending from BaseModel
• difftool was moved into a separate module and the structure of both parsing and difftool was adjusted accordingly.

Full Changelog: v0.2.1...v0.3.0

Academy Ruins API v0.2.1

What's Changed

The route replacement introduced in version 0.2.0 wasn't quite implemented properly, causing some routes to be unreachable. This has been fixed.

Academy Ruins API v0.2.0

BREAKING CHANGES

All of the routes in the Rules section of the API have been deprecated and replaced with new routes. The deprecated routes are scheduled to be removed on 2023-07-01. The responses returned by the new routes are identical to their old counterparts, only the path has been changed.

Replacements

The routes are changed as follows:

• /allrules ➡️ /cr
• /rule/{num} ➡️ /cr/{num}
• /example/{num} ➡️ /cr/example/{num}
• /keywords ➡️ /cr/keywords
• /glossary ➡️ /cr/glossary
• /glossary/{term} ➡️ /cr/glossary/term
• /unofficial-glossary ➡️ /cr/unofficial-glossary

Rationale

When Academy Ruins was first created, it was a rushed patch job trying to replace an old, suddenly unavailable API as fast as possible. In order to make the transition easier for projects, I tried to replicate 1:1 the paths that the old API was serving. With time to reflect though, I came to realize that those paths were not a great fit for what my goals are for Academy Ruins. As I plan to extend the API to include things like the parsed MTR (which is coming Soon:tm:) and IPG (and more), the specter of those old routes polluting the global namespace seems less and less bearable. Therefore, while the project is still in its fairly early stages, I decided to properly re-organize those responses into a more sensible schema.

Hopefully, since the transition should be fairly simple, six months are enough for anyone who depends on these routes to make the switch.

Other Changes

• Added the /file/cr route returning the latest raw CR file.
• The API docs have been improved to properly describe most of the site's behavior.
• Reworked the CR parser to more intelligently determine the character encoding of the source file.