Good resource for building restful API

Question

I am looking for a good resource which will show me the right way for building a restful API. Interesting topics: Authentication in particular and security in general, performance, scalability, best practices and other useful things.

I am going to build it in PHP (Slim or Silex) and before I begin I would like to think about the whole design so I can go the right way from the beginning.

There are a lot of info and posts all around the web but all of them adopt different practices and approaches.

Is there something which seems like a "standard" in the restful world?

Answer 1

Is there something which seems like a "standard" in the restful world?

Not beyond the level of using HTTP. There's a bunch of media types for encoding of API data (see hypermedia below), a lot of different best practices and a good amount of RFC's that covers various aspects of working with HTTP (like for instance authorization using OAuth2).

Here's a compilation of resources worth reading ... I think you will get the most out of reading through one or two of the books.

Authorative resources

• Fieldings original thesis on REST: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Books

• RESTful Web APIs: http://shop.oreilly.com/product/0636920028468.do
• RESTful Web Services Cookbook: http://shop.oreilly.com/product/9780596801694.do
• REST in Practice : http://shop.oreilly.com/product/9780596805838.do
• RESTful Web Services: http://amzn.com/0596529260
• Web API Design: https://pages.apigee.com/web-api-design-website-h-ebook-registration.html
• InfoQ E-magazine on REST: http://www.infoq.com/minibooks/emag-rest

Authentication

• Basic considerations: http://soabits.blogspot.dk/2014/02/api-authentication-considerations-and.html
• OAuth2 spec: https://www.rfc-editor.org/rfc/rfc6749

Error handling

• Best practices: http://soabits.blogspot.dk/2013/05/error-handling-considerations-and-best.html
• "vnd.error" a media type for error details: https://github.com/blongden/vnd.error
• Problem details for HTTP APIs: https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-http-problem-00

Hypermedia

• Fielding's fameous rant: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• Selling the benefits of hypermedia: http://soabits.blogspot.dk/2013/12/selling-benefits-of-hypermedia.html
• HAL media type: HAL: http://stateless.co/hal_specification.html
• Sirene media type: Sirene: https://github.com/kevinswiber/siren
• Collection+JSON: http://amundsen.com/media-types/collection/format/
• JSON API: http://jsonapi.org/
• Hydra: http://www.markus-lanthaler.com/hydra/
• RFC 5988 Web Linking https://www.rfc-editor.org/rfc/rfc5988

URL structures

• Basic considerations: http://soabits.blogspot.dk/2013/10/url-structures-and-hyper-media-for-web.html

Partial updates

• Considerations about partial updates: http://soabits.blogspot.dk/2013/01/http-put-patch-or-post-partial-updates.html
• JSON-Patch: https://www.rfc-editor.org/rfc/rfc6902

Answer 2

Some consideration about PHP for building rest APIs

PHP is a widely used technology since many years.

But during this long period it has shown some relevant problems: it became a monstrous technology and its usage has shown some security vulnerability like SQL injection, lack of a centralized packaging registry, inconsistent API and subpar performance. For building REST apis there are more modern technologies, like Ruby on Rails and Django, or Node.js, which is easily approachable.

Using PHP for building Rest APIS

You can of course build your apis in php also if better technologies have born in last years. Many companies still uses it in production environments. You can choose two different approach to build your infrastructure:

1. building everything from scratch interfacing directly with PHP APIs.
2. staying on an upper level and interface with third party, open source libraries to perform some tedious processes like routing, authentication and so on.

The second approach lets you save time and focus more on your business logic, by delegating some common operations to trusted third party written code.

For example you can check these libraries that are commonly used in PHP applications to get the job done faster:

1. https://github.com/chriso/klein.php helps you performing the routing

2. https://github.com/PHPAuth/PHPAuth help you with authentication process (check also https://github.com/firebase/php-jwt for stateless authentication).

3. https://github.com/mongodb/mongo-php-driver (mongodb) or https://github.com/cagartner/sql-anywhere-client (SQL) You will need to interface with a database and this links are examples of some clients libraries that helps you with the job

Using something like node.js

Node.js is a modern technologies built to allow people do what you are going to do. It's fast, scalable (php is less), easy to use and has a very frenetic community that write code and share open source.

For example, using http://expressjs.com/ you can manage the whole routing of your application in minutes. You write your application in javascript so you will have to worry about physiological javascript's problems (closures, async calls etc.), but after have solved this quite tricky part, with node.js you will build a more efficient rest APIs, and your server will need less CPU and power to accepting and answering requests.