What Makes a Great API? The Five Keys

Source: http://blog.programmableweb.com/2012/07/19/what-makes-a-great-api-the-five-keys/

5 Keys to a Great API

• Provide a valuable service
• Have a plan and a business model
• Make it simple and flexible
• It should be managed and measured
• Provide great developer support

What Makes a Great Open API? from jmusser

Top 10 API Worst Practices (Restful API)

Source: http://blog.programmableweb.com/2012/08/03/top-10-api-worst-practices/

• Poor error handling
• REST APIs that ignore HTTP rules
• Exposing your raw underlying data model
• Security complexity
• Unexpected and undocumented releases
• Poor developer experience
• Expect an MVC framework “gives” you a great API
• Assume if you build it they will come
• Inadequate support
• Poor documentation

Many of these issues came up in the developer survey that said Facebook causes the most developer pain.

Open API with Restlet

Open API with Restlet:

This talk introduces in detail how to develop a RESTful web API in Java thanks to Reslet Framework, the first open source project to offer a REST toolkit in 2005.

Learn REST: A Tutorial

http://rest.elkstein.org/2008/02/what-is-rest.html

1. What is REST?

REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

• In many ways, the World Wide Web itself, based on HTTP, can be viewed as a REST-based architecture.

RESTful applications use HTTP requests to post data (create and/or update), read data (e.g., make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

REST is a lightweight alternative to mechanisms like RPC (Remote Procedure Calls) and Web Services (SOAP, WSDL, et al.). Later, we will see how much more simple REST is.

• Despite being simple, REST is fully-featured; there's basically nothing you can do in Web Services that can't be done with a RESTful architecture.

REST is not a "standard". There will never be a W3C recommendataion for REST, for example. And while there are REST programming frameworks, working with REST is so simple that you can often "roll your own" with standard library features in languages like Perl, Java, or C#.

Designing Hypermedia APIs

Designing Hypermedia APIs:

Ruby on Rails did a lot to bring REST to developers, but its conception leaves the REST devotee feeling a bit empty. "Where's the hypermedia?" she says. "REST isn't RPC," he may cry. In this talk, Steve will explain how to design your APIs so that they truly embrace the web and HTTP. Pros and cons of this approach will be discussed, as well as why many aren't building things this way yet.

Laravel 4: A Start at a RESTful API

Laravel 4: A Start at a RESTful API:

RESTful API's are hard! There are a lot of aspects to designing and writing a successful one. For instance, some of the topics that you may find yourself handling include authentication, hypermedia, versioning, rate limits, and content negotiation. Rather than tackling all of these concepts, however, let's instead focus on the basics of REST. We'll make some JSON endpoints behind a basic authentication system, and learn a few Laravel 4 tricks in the process.