Best Practices REST API from Scratch – Introduction

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 README file, 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.

For example GET /api/contacts/12 retrieves the contact with id of 12, while PUT /api/contacts/12 will 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

Continue reading %Best Practices REST API from Scratch – Introduction%