Today we are introducing the Olery Developer Portal, a website dedicated to the Olery Review Data API, open source software released by Olery and a blog run by the engineering team of Olery.
The developer portal will replace the old Swagger based documentation due to offering greater flexibility and being much easier to maintain. Topics that will be covered are the Review Data API, review widgets, how to authenticate with the API and more.
With this new portal also comes a big set of improvements of the API documentation itself. Almost all parts have been re-written from the ground up to provide more examples, information about required parameters, data types and so forth.
One aspect that has been removed is the ability to interactively play with the API straight from the documentation. In the previous setup this was handled by Swagger but our new setup does not yet support this. We are looking into ways of re-implementing this in the future, but for now this feature is not available.
The portal is a static website generated using nanoc and is hosted on Amazon S3. Content is distributed using CloudFront to ensure optimal performance no matter one’s location. The documentation side of the portal is broken up into two two categories:
- Hand written content such as the Authentication page
- Auto generated content based on source code documentation
The auto generated content is built by taking the raw source code documentation and converting it to a generic JSON format. This format is then used to generate raw Markdown. In turn those Markdown documents are converted to HTML whenever the portal is updated. While this is quite the roundtrip the whole process is automated, making it trivial to update the portal without having to copy-paste things all over the place.
An important aspect of a documentation platform is the ability to search the content easily. This allows readers to quickly find what they need, without having to click through every page by hand.
To ensure optimal performance the indexes used by lunr are pre-generated whenever the portal is updated. The result is a search system that performs surprisingly well without the need of complex server infrastructure.
Last, the portal will feature a blog managed by the engineering team of Olery. This blog will feature both news updates related to the various APIs as well as more general, technically oriented articles. The blog also has an Atom feed which can be used by one’s feed reader of choice.
In case you’d like to know more about the developer portal or its underlying technology, feel free to contact us at firstname.lastname@example.org.
written by Yorick Peterse