API development:
problems, solutions,
and best practices

by Enrico Zimuel / @ezimuel
Senior Software Engineer - Zend Technologies

About me

I'm a Software Engineer since 1996. I work in the R&D department of Zend Technologies, the PHP Company based in Cupertino (California). I'm an open source contributor. I did research in computer science at the Informatics Institute of the University of Amsterdam. I'm a remote worker, based in Turin (Italy).

Web API development

RESTful in a nutshell

• Exposes resources, a resource can be everything
• A resource is identified by a unique URL
• A resource is represented using a format (e.g. JSON)
• Hypermedia API, connections (links) between resources
• HATEOAS, Hypermedia As The Engine Of Application State

Glory of REST

When talking about REST, the Richardson Maturity Model is often used to describe the concerns necessary when implementing a well-designed REST API

Advantages of REST

Scalable architecture

Very easy to consume

Reduce client/server coupling

Discoverability

RESTful in practice?

Can be difficult, especially at the beginning

Some questions

• What representation formats will you expose?
• How will you report errors?
• How will you advertise which HTTP methods are available for a given resource?
• How will you handle features such as authentication?
• How will you handle hypermedia linking?
• How will you document what resources are available?

Possible answers

• What representation formats will you expose? JSON
• How will you report errors? application/problem+json
• How will you advertise which HTTP methods are available for a given resource? OPTIONS
• How will you handle features such as authentication? OAuth2
• How will you handle hypermedia linking? Hypermedia Application Language (HAL)
• How will you document what resources are available? Swagger, Apiary.io, API Blueprint, etc

Apigility

• API builder for PHP applications, the world's easiest way to create high-quality APIs
• Open source project by Zend Technologies
• Built using Zend Framework 2 (modules)
• Version 1.0.0beta3 released in April 2014
• http://www.apigility.org

Main features

• RPC and REST
• JSON (HAL) as default format
• Error handling (API Problem)
• Content negotiation
• Versioning (via URI and Accept header)
• Filtering and validation
• Authentication (HTTP Basic/Digest, OAuth2)
• Interactive documentation (HTML, Swagger)

JSON HAL

• JSON Hypertext Application Language, is a RFC draft proposal (draft-kelly-json-hal-06)
• Example:

  
  GET /api/user/ezimuel
  
  {
      "_links": {
          "self": {
              "href": "http://domain/api/user/ezimuel"
          }
      }
      "id": "ezimuel",
      "name": "Enrico Zimuel"
  }
  

_embedded

{
    "_links": {
        "self": {
            "href": "http://domain/api/user/ezimuel"
        }
    }
    "id": "ezimuel",
    "name": "Enrico Zimuel",
    "_embedded": {
        "contacts": [
            {
                "_links": {
                    "self": {
                        "href": "http://domain/api/user/mwop"
                    }
                },
                "id": "mwop",
                "name": "Matthew Weier O'Phinney"
            },
            {
                "_links": {
                    "self": {
                        "href": "http://domain/api/user/ralphschindler"
                    }
                },
                "id": "ralphschindler",
                "name": "Ralph Schindler"
            }
        ]
    }
}

Collections

{
    "_links": {
        "self": {
            "href": "http://domain/api/user?page=3"
        },
        "first": {
            "href": "http://domain/api/user"
        },
        "prev": {
            "href": "http://domain/api/user?page=2"
        },
        "next": {
            "href": "http://domain/api/user?page=4"
        },
        "last": {
            "href": "http://domain/api/user?page=133"
        }
    }
    "count": 3,
    "total": 498,
    "_embedded": {
        "users": [
            {
                "_links": {
                    "self": {
                        "href": "http://domain/api/user/mwop"
                    }
                },
                "id": "mwop",
                "name": "Matthew Weier O'Phinney"
            },
            {
                "_links": {
                    "self": {
                        "href": "http://domain/api/user/mac_nibblet"
                    }
                },
                "id": "mac_nibblet",
                "name": "Antoine Hedgecock"
            },
            {
                "_links": {
                    "self": {
                        "href": "http://domain/api/user/spiffyjr"
                    }
                },
                "id": "spiffyjr",
                "name": "Kyle Spraggs"
            }
        ]
    }
}

API Problem

• API Problem is a RFC draft proposal (draft-nottingham-http-problem-06)
• Example:

  
  Content-Type: application/problem+json
  
  {
      "detail": "The GET method has not been defined for individual",
      "status": 405,
      "title": "Method Not Allowed",
      "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
  }
  

API Versioning

Agility uses two approaches:

• In the URL, e.g. /api/v1/user
• By Accept header, e.g. Accept:application/vnd.example.v1+json

Authentication

Apigility supports three different authentication systems: HTTP Basic, HTTP Digest, and OAuth2

Installation

Super easy, just one command:

$ curl -sS https://apigility.org/install | php

Or, if you don't have CURL installed:

$ php -r "readfile('https://apigility.org/install');" | php

Apigility UI

Open the browser to http://localhost:8888

DEMO time

Apigility in action!

Thanks!

More information on apigility.org

Contact me: enrico [at] zend.com

Follow me: @ezimuel

This work is licensed under a
Creative Commons Attribution-ShareAlike 3.0 Unported License.
I used reveal.js to make this presentation.