When it comes to documenting the APIs (especially the REST ones), having the cURL samples that one can try out and play around with has become the defacto standard these days. However if you actually want to read through the response body, look up certain piece of information or just simply check the integrity of the response itself, you will run into a big inconvenience that comes with cURL – the format of the response body. Don’t get me wrong, I love cURL as much as the next guy, but the things can be improved upon. And that is the aim of this article.
There are many aspects one must take into consideration when it comes to picking the right board for their project – from performance, memory, battery life, available slots for SD cards or bee modules all the way to the connectivity, namely network interface. Whether it is wired or wireless network interface, it plays crucial role in the way the board is deployed, controlled and it influences the memory and power consumption. In this post I will be discussing the way to setup your Arduino-compatible board as an HTTP client. I have been using my Seeedstudio Stalker v2.3 for all the tests I am describing in this post.
Continue reading “Arduino as a wireless HTTP client”
I tackled details of integration, documentation creation as well as exposition of documentation using Swagger and its module Swagger UI. One of obvious shortcomings that might be serious concern for people managing their API documentation is fine-grained control over what is published and what stays hidden. There are several reasons to decide to hide something from users. First might be the lack of relevance of introspected information that just don’t belong to the documentation. Other big issue might be security concerns as well as the design of API documentation itself.
Once you create API documentation it is important to make it available to the stakeholders. In ideal case, this published documentation would be flexible enough to account for any last-minute changes and also be easy to distribute (in terms of costs as well as time needed to accomplish this). To make this possible we will make use of what was accomplished in my previous post detailing the process of creation of API documentation. Using Swagger UI module in combination with published API documentation in json allows us to create simple HTML documentation that may be used to interact with the APIs as well.
The real key to making your REST API easy to use is good documentation. But even if your documentation is done well, you need to set your company processes right to publish it correctly and on time. Ensuring that stakeholders receive it on time is one thing, but you are also responsible for updates in both the API and documentation. Having this process done automatically provides easy way out of trouble, since your documentation is no longer static deliverable and becomes a living thing. In previous post, I discussed how to integrate Swagger with your Spring application with Jersey. Now it’s time to show you how to create documentation and publish it for others to see.