Interface Representation Patterns: Crafting and Consuming Message-Based Remote APIs

Remote Application Programming Interfaces (APIs) are technology enablers for major distributed system trends such as mobile and cloud computing and the Internet of Things. In such settings, message-based APIs dominate over procedural and object-oriented ones. It is hard to design such APIs so that they are easy and efficient to use for client developers. Maintaining their runtime qualities while preserving backward compatibility is equally challenging for API providers. For instance, finding a well suited granularity for services and their operations is a particularly important design concern in APIs that realize service-oriented software architectures. Due to the fallacies of distributed computing, the forces for message-based APIs and service interfaces differ from those for local APIs -- for instance, network latency and security concerns deserve special attention. Existing pattern languages have dealt with local APIs in object-oriented programming, with remote objects, with queue-based messaging and with service-oriented computing platforms. However, patterns or equivalent guidance for the structural design of request and response messages in message-based remote APIs is still missing. In this paper, we outline such a pattern language and introduce five basic interface representation patterns to promote platform-independent design advice for common remote API technologies such as RESTful HTTP and Web services (WSDL/SOAP). Known uses and examples of the patterns are drawn from public Web APIs, as well as application development and software integration projects the authors have been involved in.