Web Platform API Design Principles and Service Contract

The emergence of web services gives rise to service ecosystems, where core service platforms are exposed through APIs to a large number of third parties to provide new solutions. This often requires platform APIs to be able to evolve rapidly while not breaking backward compatibility in order to support a wider range of planned and unplanned use. The REST architecture style allows a service contract to be negotiated and delivered at runtime aiming to achieve higher level of evolvability. However this potential is often not fully realized due to the lack of systematic approach in architecture design to separate requirement-related contract elements from specification-related elements and integrate them into the overall API design. In this paper, we present a novel approach to designing service platform APIs in order to achieve high evolvability. We firstly apply the problem frames approach to better understand the interface coupling and the evolution of requirements. Based on the problem frame analysis, we propose a media-type centric approach to designing RESTful service API. We applied our approach to the Twitter API evolution. The result shows significant improvements in the areas of contract leaking prevention, interface consistency and adding new features.