Web Architecture, Java Ecosystem, Software Craftsmanship

Rest

RESTful API Documentation with Swagger and AsciiDoc

Posted on Feb 19, 2017

RESTful API Documentation with Swagger and AsciiDoc

Writing documentation manually for a RESTful API can be laborious. On the other hand, relying exclusively on the generation of the documentation (e.g. with swagger-ui) is often not sufficient. There are always aspects (like common use cases and workflows) that need to be described manually. Let’s see how we can combine these two approaches with the help of AsciiDoc!

Testing RESTful Services in Java: Best Practices

Posted on Mar 29, 2016

Testing RESTful Services in Java: Best Practices

Testing RESTful Web Services can be cumbersome because you have to deal with low-level concerns which can make your tests verbose, hard to read and to maintain. Fortunately, there are libraries and best practices helping you to keep your integration tests concise, clean, decoupled and maintainable. This post covers those best practices.

Enriching RESTful Services with Swagger

Posted on Jul 28, 2015

Enriching RESTful Services with Swagger

Consuming RESTful services can be a laborious task, because there is much low-level-work to do. Jealously we looked at the WS*/SOAP guys: They can easily generate a nice client API based on the formal interface specification WSDL. This significantly simplifies the service consumption. For a long time the REST world lacks a widespread formal specification and generation tools. But Swagger sets out to change this.

RESTful API Design. Best Practices in a Nutshell.

Posted on Mar 4, 2015

RESTful API Design. Best Practices in a Nutshell.

How does the URL for my resource should look like? Plural or singular nouns? How many URLs do I need for one resource? What HTTP method on which URL do I use for creating a new resource? Where should I place optional parameter? What about URLs for operations that don’t involve resources? What is the best approach for pagination or versioning? Designing RESTful APIs can be tricky because there are so many possibilities. In this post, we take a look at RESTful API design and point out best practices.