We share our inquisitive musings.

REST API server

on-IDLE developers are comfortable REST API consumers. We regularly read Twitter, Facebook, Instagram and any other REST JSON API. In 2018 we were facing a new challenge: to build a REST API server ourselves for a successful client's lead portal. The aim of the solution was for retailers and various external parties to read available offers and push sales leads directly from their intranet to our client's partner platform and mobile applications.

We had to meet the following requirements:

  1. Secure and with limited request to not overload app server
  2. Fast responses
  3. Write documentation with examples
  4. Write it in a way that it is easily maintained and can be extended

We created the following endpoints:

  • Offers: DB source – TV, Broadband, Phone and Mobile offers, which differ from client to client. We had to customise responses depending on client ID since each client could have custom prices. Using REST API HTTP GET method, several response codes available, 200 for success with JSON as body.
  • Orders: DB target – We had to save many fields from basic customer/agent information to sensitive data such as bank details. Using the REST API HTTP POST method, several response codes were available, 200 for success with JSON returning order details (including UID).
  • Postcodes: 3rd party API source – Which TV, Broadband, Phone and Mobile services are available depends on the customer's location, so we had to connect to 3rd party data with postcodes for our customer/agent needs.

API clients were authorised via OAuth 2.0

Standardised HTTP responses depending on the client-server behaviours.

CRUD API Listener and Throttle

Since we are PHP developers using the CakePHP framework, we were happy to use the CRUD plugin with API listener and also the Throttle plugin to limit the number of HTTP requests.

We built the online and PDF documentation with Sphinx, using a theme provided by reading the Docs.

In September 2018, after a month of development and testing, we successfully launched the API, which since serves thousands of requests every day and brings in thousands of orders.