This content is part of the Essential Guide: Guide: When and how to use REST

Thinking like a developer for better REST interfaces

Organizations need to think about a developer’s needs in the development or deployment of RESTful services. Read this tip by George Lawton that will help create better REST interfaces.

Organizations need to think about a developer’s needs in the development or deployment of RESTful services. Some of the best practices for this process include keeping the REST interfaces simple and consistent as well as providing good error feedback when exceptions occur. In addition, organizations also need to think about the infrastructure required to maintain service level agreements (SLA) after the application program interface (API) has been deployed.

Chris Haddad, vice president of Technology Evangelism at WSO2, said that applying governance to RESTful APIs is important for business processes that depend on them. A managed API needs to be available with SLAs in a manner that is secure, authenticated, authorized and protected. There are many challenges facing good RESTful API management. Potential consumers may not trust API stability, reliability or performance. There are also security risks that can prevent publishing and offering open access.

There are two levels of governance with respect to RESTful APIs. Design time governance looks at how to create a resource that is stateless, has a resource oriented URL convention and which supports security. Operational governance looks at the average and peak throughput needed for the API in order to ensure a guaranteed SLA. This form of governance looks at the consuming clients, and the hardware and software configurations required to support their needs. It also necessitates a system for monitoring the APIs with the ability to alert managers via SMS or email when a fault is detected.

Haddad recommends sticking with the methods provided by the HTTP protocol including GET, POST, PUT and DELETE for RESTful services. Organizations need to ensure that these are not implemented with side effects that change the state of the system in unexpected ways. For example, PUT should update the resource in place. The GET, HEAD, OPTIONS and TRACE methods should not modify anything.

Haddad also recommends using State Chart (SCXML), which provides a state machine notation for API control that can be incorporated into an approval model. A variety of tools support SCXML including IBM Rational Software Architect, SCXMLgui and in the future WSO2 Carbon.

Keeping it simple

In a recent Webcast, Brian Mulloy, VP of Products at Apigee, said a good place to start is with a virtualization layer on top of the API, which insulates developers from any of the logic underneath. This allows organizations to fine tune the logic underneath the API, without burdening the developers with these changes. He noted that some APIs, such as those for have up to 20 versions, which can confuse developers.

He also recommends keeping the version names simple, and to refer to them with a “v” followed by an integer. Incorporating a decimal point into the version number can cause the developer anxiety at the implication that it could be constantly updated.

Download Apigee’s free eBook on WEB API Design for more tips

WSO2 Webinar on RESTful API Governance

Mike Amundsen’s Hypermedia Types project for better RESTful messaging

While it is easy to get lost in the abstract principals of REST design, it is more important to simplify life for developers. This includes reducing the number of URIs required to access services. Web applications can reduce the number resources by making extensive use of the POST, GET, PUT and DELETE commands.

As a matter of convention, Mulloy also recommends that resources be specified as nouns because these better match a developer's expectations and thought flow. However, verbs are useful when submitting requests for an algorithmic response, such as currency conversion.

Mulloy also takes a stand for more concrete naming of resources. For example, he points out that the BBC uses the high level abstraction of “item” to make requests across all of its different resources. But it would be more compelling for a developer to see resources for blogs, news, reports and video clips, because it would make it more visceral and easier to program with.

Effective error reporting for REST interfaces is an important aspect in helping developers write working code and in finding underlying bugs in the Web application. “The errors are one of the key pieces of visibility into the API,” said Mulloy. Not only will the developer access the API during the development process, it will also help them find problems after the program has been deployed in the wild.

Mulloy recommends that the API translate error messages into standard HTTP error codes. For example, Facebook returns an arbitrary number with no additional context which makes life confusing. In contrast, Twilio plugs the codes into HTTP status codes, and provides a more granular error message.

This upfront work reduces the amount of time a developer spends interpreting codes. In the cases where more complicated codes are generated, Twilio also provides a URL for the message back to its developer community site. This helps provide a forum for developers to identify and correct programming errors more quickly.

There are a wide variety of authentication methods for RESTful services. While some websites, like PayPal have developed their own proprietary method, Mulloy recommends that companies adopt OAUTH 2.0, which simplifies lives for developers in accessing restricted services.

Simplify resources with better messaging

While the common practice in designing RESTful APIs has been to focus on more comprehensive URIs, Mike Amundsen, Layer 7’s principal API architect argues that it makes more sense to focus on better messaging rather than direct protocol methods. He wrote, “The key to creating a powerful API, it turns out, is in the design of the messages sent back and forth between parties. Reliable and evolvable API design is based not on function calls and shared objects but on hypermedia-style messages.”

To address this need, Amundsen has been working on a framework for understanding hyper media types, using a concept called H-Factors. These can be used to create an API with the flexibility, usability and longevity of Web pages. In this case, the URIs can be kept simple, and new features can be added by extending the types of messages supported.

Dig Deeper on Topics Archive