RESTful Services in an Enterprise Environment : A Comparative Case Study of Specification Formats and HATEOAS

Abstract: RESTful services are becoming increasingly popular. This work, that was carried out at Scania IT, investigates how a RESTful service should be designed and specified so that it meets the demands of an enterprise environment. In particular, this report will focus on documentation and validation of RESTful services, i.e. specifications. These are important aspects in an enterprise environment. The investigation consists of a comparative case study of four specification formats and Hypermedia As The Engine Of Application State (HATEOAS). The results show that the most commonly used specification formats have flaws. They also suggest that Swagger and RAML (RESTful API Modeling Language) are the two most mature formats. The results also show that HATEOAS, which is a more dynamic approach, can be useful in an enterprise environment but that it requires careful design.