New WSO2 White Paper Provides In-depth Examination of Best Practices for Designing RESTful APIs

Paper discusses proven approaches for creating secure, high-performance APIs that reach Level 2 of the Richard Maturity Model for APIs based on a REST architecture

Mountain View, CA – May 4, 2016 – Today, a majority of APIs are based on a REST architecture, since its lightweight structure and low use of bandwidth are well suited to a range of web, mobile and Internet of Things (IoT) applications. However, the effectiveness of a REST API is only as good as its design. A new white paper from WSO2 provides guidelines, based on proven industry best practices, on how to develop a REST API that reaches Level 2 of the Richardson Maturity Model.

Mastering RESTful APIs

The white paper, “WSO2 REST API Design Guidelines,” was authored by Professor Dr. Frank Leymann, director, Institute of Architecture of Application Systems, University of Stuttgart together with the WSO2 technical team.

The paper begins by explaining the decision to focus Level 2 of the Richardson Maturity Model, which grades APIs according to the constraints of REST, noting that Level 3 is not yet supported by the breadth of accepted best practices as Level 2. It then provides a top-level overview of the major steps that should be followed in creating a RESTful API.

Next, the paper dives into the details of each step and supporting actions, including how to:

• Create a data model to describe the data that will be manipulated by the API.
• Create a resource model that specifies the resources the API will process, such as atomic, collection, composite, controller, and processing function resources.
• Create uniform resource identifiers (URIs), including proper naming and schemes, as well as the host, base path, version, URI templates, and query string.
• Specify the representation of each resource, which also requires deciding on a data structure for the information content.
• Manipulate resources in the REST method using create, retrieve, update and delete (CRUD) operations that map to the HTTP methods: POST, GET, PUT and DELETE.
• Use HTTP headers to provide a vehicle for non-functional properties of REST APIs.
• Implement status codes in response messages to provide key information to clients about the status of a request.
• Determine any special behaviors that need to be addressed, such as content negotiation, queries, pagination, client-side caching, concurrency control, and long-running requests.
• Determine how reporting errors will be handled.

The paper then examines how to secure resources of the API by making them accessible on a properly designed permission model that prevents the misuse of APIs. Among the approaches examined are HTTP Basic Authentication, Open Authorization (OAuth) tokens, and the eXtensible Access Control Markup Language (XACML) for a more fine-grained control of access to resources. It then concludes by reviewing the implications of security approaches on API design.

The white paper can be downloaded at https://wso2.com/whitepapers/wso2-rest-apis-design-guidelines.

About the Authors

Professor Dr. Frank Leymann is a full professor of computer science and founder and director of the Institute of Architecture of Application Systems (IAAS) at the University of Stuttgart, Germany.

Joseph Fonseka is a senior technical lead at WSO2 and a member of the WSO2 API Manager team, focusing on research and development. He is also interested in API architecture and API design within enterprises.

Sanjeewa Malalgoda is an associate technical lead at WSO2 and has been a key member of the WSO2 API Manager team since its inception. He has been actively involved in designing and building API management solutions for WSO2 customers, including many Fortune 500 companies.

Nuwan Dias is a technical lead at WSO2. As the product lead of WSO2 API Manager, his primary focus revolves around research and development activities of the product.

Sameera Medagammaddegedara is a senior software engineer at WSO2, working on the WSO2 Enterprise Store and WSO2 Governance Registry teams.

Malintha Amarasinghe is a software engineer on the WSO2 API Manager team. His areas of interest include web services, machine learning, and robotics.

About WSO2

WSO2 empowers enterprises to build connected businesses and accelerate their pace of innovation with the industry’s only lean, fully integrated, and 100% open source enterprise middleware platform. Using WSO2’s platform, enterprises have all the functionality to build, integrate, manage, secure and analyze their APIs, applications, Web services, and microservices—on-premises, in the cloud, on mobile devices, and across the Internet of Things. Leading enterprise customers worldwide rely on WSO2’s platform and its robust performance and governance for their mission-critical applications. Today, these businesses represent nearly every sector: health, financial, retail, logistics, manufacturing, travel, technology, telecom and more. Visit https://wso2.com to learn more, or check out the WSO2 community on the WSO2 Blog, Twitter, LinkedIn and Facebook.

Trademarks and registered trademarks are the properties of their respective owners.