How to deal with big API Description Document
How big is a big API Description Document? The breaking point is currently 1MB. Once your API Description Document size is over 1MB, you will run into some issues when using Apiary.
Issues with documents over 1MB
A document over 1MB is usually tens of thousands of lines long. You shouldn’t worry about document size until you are working on API Description Project of this scope.
- GitHub Sync and GitHub Integration will stop working, because of 1MB file size limit in GitHub API
- Editing this API Description Document in Apiary Editor will be consume substantial system resources. Previews and warning will get notably delayed.
- Once you are way above 1MB limit, you could encounter timeouts in UI and in tools that relies on API Description Document parsing
How to deal with big API Description Documents
There are some strategies to deal even with really large API Description Documents.
- If you are using API Blueprint, switch to MSON data structures. Not having to repeat JSON payloads will make your API Blueprint leaner, easier to read and write, and more consistent.
- If your API Description Document is this big, it’s most likely also too big for API users to read, understand and use. Consider splitting your API Description Document into domains/areas/services, whatever makes sense in your context. Smaller documentations will be easier to manage, write and read.
- We also advise against embedding binary resources (like images, zips…) and instead use JSON Schema
- You can always contact our support, if you run into issues with big API Description Documents