Vito Tardia (a.k.a. Ragman), is a freelance web designer and developer living near Como, Italy. He works for various types of clients, from small and medium businesses to well-known web agencies. He offers basically two services: he can help you solve problems and achieve goals, by using technology, the internet and a good amount of creativity and chutzpah. In practice, Vito builds web sites and applications with fanatical attention to detail applying industry best practices. Vito is also a skilled guitarist and music composer. His music adventure started back in 1996 with the power metal band Pandaemonium and their album …and the Runes begin to pray. Since then, he enjoys jamming with local (hard) rock bands.
We ended the first part of this tutorial with all the basic layers of our API in place. We have our server setup, authentication system, JSON input/output, error management and a couple of dummy routes. But, most importantly, we wrote the
READMEfile that defines resources and actions. Now it’s time to deal with these resources.
Creating and updating contacts
We have no data right now, so we can start with contact creation. Current REST best practices suggest that create and update operations should return a resource representation. Since the core of this article is the API, the code that deals with the database is very basic and could be done better. In a real world application you probably would use a more robust ORM/Model and validation library.
The current internet ecosystem has literally been invaded by APIs, and for good reasons. By using third party APIs in your products or services, you have access to a ton of useful features — such as authentication or storage services — that can benefit both you and your users. By exposing your own API, your application becomes “part of the mix” and will be used in ways you’ve never thought before… if you do it the right way, obviously.
In this two part series I’ll show you how to create a RESTful API layer for your PHP applications, using a collection of real world best practices.
The full source code of this project will be available at the end of part 2.
A pleasant UI for developers
First of all, an API is a user interface for developers, so it must be friendly, simple, easy to use and of course pleasant; or else it will end up being another piece of digital junk out there.
Documentation, even in the form of a simple but well written
READMEfile, is a good place to start. The minimal information we need is a summary of the service’s scope and the list of methods and access points.
A good summary can be:
Our application is a simple contact list service that manages contacts with linked notes. It has two object types, contacts and notes. Each contact has basic attributes such as first name, last name, and email address. Also, each contact can have a number of markdown-formatted notes linked to it.
Then, it’s a good idea to make a list of all the resources and actions that we are going to implement. This can be seen as the equivalent of wireframing for visual applications. Following the key principles of REST, each resource is represented by a URL, where the action is the HTTP method used to access it.
GET /api/contacts/12retrieves the contact with
idof 12, while
PUT /api/contacts/12will update that same contact.
The full list of methods is displayed below:
URL HTTP Method Operation /api/contacts GET Returns an array of contacts /api/contacts/:id GET Returns the contact with id of :id /api/contacts POST Adds a new contact and return it with an id attribute added /api/contacts/:id PUT Updates the contact with id of :id /api/contacts/:id PATCH Partially updates the contact with id of :id /api/contacts/:id DELETE Deletes the contact with id of :id /api/contacts/:id/star PUT Adds to favorites the contact with id of :id /api/contacts/:id/star DELETE Removes from favorites the contact with id of :id /api/contacts/:id/notes GET Returns the notes for the contact with id of :id /api/contacts/:id/notes/:nid GET Returns the note with id of :nid for the contact with id of :id /api/contacts/:id/notes POST Adds a new note for the contact with id of :id /api/contacts/:id/notes/:nid PUT Updates the note with id if :nid for the contact with id of :id /api/contacts/:id/notes/:nid PATCH Partially updates the note with id of :nid for the contact with id of :id /api/contacts/:id/notes/:nid DELETE Deletes the note with id of :nid for the contact with id of :id
In my previous article we've discovered the basics of PHP Streams and how powerful they were. In this tutorial we are going to use this power in the real world. First I'll show you how to build your custom filters and attach them to a stream, then we'll package our filters inside a document parser […]
Streams are resources provided by PHP that we often use transparently but which are also very powerful tools. They were introduced as a way of generalizing file, network, data compression, and other operations which share a common set of functions and uses. By learning how to harness their power, we can take our applications to a higher level.
Apple’s Passbook is a very interesting piece of technology that involves a lot of well-known and loved tools like JSON and RESTful APIs. See how to build a sample web app that creates and distributes passes. Though the example presented isn’t a full-featured product, it can serve as a nice base to build on for more serious real world uses.
The ePub format is a publishing standard built on top of XHTML, CSS, and XML. And since PHP is well suited for working with HTML and friends, why not use it to build ebooks? In this article you’ll see how to build a tool for creating ePub packages. Maybe it’s your next best selling cyber-sci-fi novel or documentation for your latest code project… because we all write good documentation for our projects, don’t we?
Mozilla Persona is created and sponsored by the Mozilla Foundation and presents itself as an easier and more secure alternative to OpenID and OAuth. With just a few easy steps you can integrate this new, future-ready distributed authentication system today, even before it’s natively supported by both the browser and email providers.
Have you ever deployed your application to the cloud? It’s not really as scary as it sounds, and in this article you’ll see the best practices for developing a well-structured application with CakePHP and then deploy it instantly to the cloud with AppFog.
This article covers two topics: deploying an application to the AppFog cloud provider, and best practices for a well-structured PHP application. First we’ll build a simple note-taking application using CakePHP and its automated bake command. Then, I’ll show you one way to structure the application separating its components into: application code application data and settings […]
Elastic Load Balancer acts as a front end for one or many of your virtual servers. It accepts requests and distributes them among virtual servers. This article will show you how to use Amazon DynamoDB as a storage facility for PHP sessions.