alberto56 / api_contract

Formalize and test the API interface between a client and server

API Contract

Formalize and test the API interface between a client and server.

Introduction

API Contract is an implementation of design by contract applied to APIs, for API implementors and API consumers.

Let's say you are developing two systems which are communicating together through a RESTful API, a problem often arises where the API itself is documented in a wiki, and is therefore immediately out of date.

Using API Contract, you can write a CSV with examples of requests and responses, and then use src/APIContract.php to:

• Provide the API consumer (frontend) with the correct responses to example inputs.
• Test the API implementor (backend) by making sure it returns the correct responses for each given example input.

Other resources and projects

API Contract is meant to be very simple and applies to PHP projects only; it is mainly a proof of concept. If you are looking for something more robust, please see the following resources:

• Blog post: API as the definition of the truth
• Project: API blueprint
• Project: Swagger
• Project: RAML
• Project: Pact

Installation

Basic installation with examples

git clone https://github.com/alberto56/api_contract.git
cd api_contract
cp examples/plurals/frontend/example.settings.php examples/plurals/frontend/settings.php
cp examples/plurals/backend/example.settings.php examples/plurals/backend/settings.php
git submodule init
git submodule update

Example code and tests will require that certain files be accessible via HTTP. If you wish to try the examples or run tests, you must be able to visit examples/plurals/frontend/index.php and examples/plurals/backend/index.php on a web browser. If this project is available at http://localhost/api_contract, so that http://localhost/api_contract/examples/plurals/frontend/index.php gives you a simple form, then you have finished installation. Otherwise, modify the following two files and set $settings['frontend_server'] and $settings['backend_server']:

• ./examples/plurals/frontend/settings.php
• ./examples/plurals/backend/settings.php

Example code

This project contains example code to demonstrate how it might be used. Please note that it is not meant to be used as is, just as an example.

Example: Plurals

You have a project to display plural forms of English nouns. You separate your developers into two teams:

• Team A designs the front-end, which allows people to enter a noun in the singular version.
• Team B designs the back-end, which stores the plural versions of nouns and provides a RESTful interface to the front-end.

Problems will arise when you start documenting the API interfacing Team A and Team B. Nothing guarantees that the API documented in the Wiki is the same as the one used by Team A and Team B.

The API interface as a project

The approach proposed here is to not document the API interface, but to release it as a full fledged versioned project.

Take a look at the examples/plurals/api folder herein.

The idea is that the API Contract is a bona fide project. In a real-world project, the API contract would have its own issue queue and git repo.

Certain principles

• The API consumer (frontend) developers have access to the API contract
• The API implementor (backend) developers have access to the API contract
• The API contract has its own git repo and issue queue
• To change the API, teams work together by modifying the API Contract post.csv file via the issue queue.

How to run automated tests

• Install PHPUnit
• Run phpunit ./ from the command line at the root of the project.

Continuous integration

There is currently an open issue for integration with the Travis CI continuous integration platform.

api_contract's Issues

Improve documentation, comments, and class/function names

Some classes have no documentation, and some classes or functions have no or bad comments. Certain classes and functions have names which do not communicate what they do.

Integration with travis CI

Allow GET types in addition to POST types

First version of example frontend with working test

Use Docker for installation and testing

Build server example

We have a frontend example with tests. we now need a server example

Make sure it is possible to install from scratch

Tests and code working on dev environment, I will need to install this from scratch and update my steps in the README.md file.

Rename project to apicontract

API contract seems like a better name for the project.