Introduction

The Bristol SU Portal API Client simplifies the process of consuming the portal API from other systems. It provides a simple set of methods, matching up to API endpoints, to let anyone use the portal API without needing a good understanding of the portal API. it also simplifies the authentication significantly, and provides tools to handle pagination etc.

The API Client can also be easily extended, to allow any module to add its API to the client. This documentation will predominantly cover extending the API client to provide additional functionality to developers trying to use your modules API.

The Architecture

The API Client allows for a very simple extensible system. For each module that provides functionality to the API client, there will be a single entry point through a class. These classes are called Client Resource Groups. Each module must have one and only one Client Resource Group.

Each Client Resource Group can give access to multiple Client Resources. There should generally be a Client Resource class per RESTful resource accessible through your API. For example, in an 'upload file' module with files and comments, you’d have two Client Resource classes - a File and a Comment.

These Client Resources each contain a set of methods, which make the http calls via the API and return a model/array of models for the user to use.

Example 1. A user wants to get all files

architecture

  1. The user creates an instance of the API Client

  2. They retrieve your module Client Resource Group, Upload File

  3. They retrieve your module Client Resource, a File

  4. They call a method, getAll to make an HTTP request

  5. The HTTP request passes back an array of File models.

  6. The Client Resource passes these back to the user

From a user point of view, if $client contains the API Client, all they need to do is

$response = $client->uploadFile()->file()->getAll();
$files = $response->getBody();

The variable $files now contains an array of files, retrieved through your module API. The variable $files now contains an array of files, retrieved through your module API.

The rest of this documentation will take you through the specifics of setting up your Client Resource Group and Client, and how to make the HTTP requests.

There is other documentation available to explain how to use the API client as a developer.