Good resource for building restful API - php

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:
building everything from scratch interfacing directly with PHP APIs.
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:
https://github.com/chriso/klein.php helps you performing the routing
https://github.com/PHPAuth/PHPAuth help you with authentication process (check also https://github.com/firebase/php-jwt for stateless authentication).
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.

Answer 3

For best practices there is a good guideline repository on GitHub. You can go to the following page for more information:
http-api-design
You can also look at Apiary to design APIs:
Apiary
For authentication actually the best thing to do is to rely on a framework instead of reimplementing from scratch. For learning purposes however thats a different case but for putting it out to production the best bet is to use what the framework provides. Most frameworks have a good implementation which probably has been iterated over time by the community to be quite robust. Certain frameworks like laravel also provides solution for csrf (cross site request forgery) attacks.
Another useful thing that you can look into is JWT (JSON Web Token). Here is useful link which summarises why it is so awesome:
Stateless tokens with JWT
I don't know how to look into scalability from an API perspective. To me it seems more like an infrastructural issue. However with authentication (session or token based) scalability could become an issue as for example if you have different number of instances serving your users you need to maintain either sticky session or session stored in a quick access key-value store or database.

Answer 4

Please have a look at my opinionated presentation about REST APIs based on JSON-LD, SemWeb, Hydra Core.