Accessing REST API Swagger Index

Owned by Ryan Mahoney
Last updated: Sept 13, 2023 by Ian Weeks (Unlicensed)
3 min read

The REST API is a charged module. Please contact PICS sales team to arrange access.

This documentation is aimed at developers integrating via the PICS REST API, and assumes knowledge of RESTful web services and JSON.

The PICS REST API comes bundled with an API Swagger index page that describes the available functions (end points) available together with the required and optional parameters and the expected response objects. 

Accessing API Swagger Index

You can access the API Swagger page using a web browser at /api/swagger/index.html therefore if your PICS web domain is:

https://trainingproviderltd.picsweb.co.uk/app/

Then your API Swagger page URL will be:

https://trainingproviderltd.picsweb.co.uk/app/api/swagger/index.html

You will then be presented with all the available end points, grouped into functional areas:

Understanding API Swagger index

The Swagger page makes use of collapsible content to make it easier to find the end point you are looking for. Each functional area can be collapsed, as can each end point.

For each end point, we include the method to use (GET, POST, PUT or DELETE), the URL to use, and a summary of what to expect. You can click on any end point to expand further details about it. For instance, if we expand the end point to "Functional Skills Literacy" you will see something like the following: 

 

Here you can see the parameters required, and the expected response, represented by default as JSON. 

Parameter Types

Each parameter defined will include the data type, whether it is required or optional, and where the parameter is expected as part of the request:

  • Path: Part of the main URL

  • Query: A URL query parameter in the mode PARAMNAME=PARAMVALUE

  • Body: Part of the body of the request - for POST and PUT requests typically. 

If the parameter is an object, an example representation will be shown, again in JSON by default.

Schemas - Object Reference

At the bottom of the API Swagger Index we have the Schemas section. In here we define each of the objects used as either a request or a response object to an end point as a summary reference to each field and it's type. To view a specific object definition, you simply click to expand it: 

DateTime Format

The datetime format supported by the REST API is ISO 8601. Example: 2023‐09‐13T10:21:06Z For dates only, please use 00:00:00 for the time section.