Getting Started on Hires API

All testing of the APIs must occur on the TEST environment. Subscription keys are associated to a specific Product and environment (LIVE/TEST) meaning that both the URL and Subscription Key have to be valid for that endpoint to accept the request.

Initial Connectivity Testing

To assist with connecting to the APIs, a few endpoints have been exposed to assist with these initial connectivity tests. Browse to the Hire API by browsing to APIs and select correct API. For the below tests, the API will be Hire API - test - v1.

Once the endpoint for the selected API are showing, check that Group by tag is on to ensure the endpoints are grouped by API route.

The below tests are for the Hires API group

  1. Get Greeting

    • Locate GET - Get a greeting and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

    • Click the red Send button at the bottom of the side bar and you should receive a greeting and local time of server (like below)

      • HTTP/1.1 200 OK

      • "Hello from Hire API. The local server time is 2024-08-20 14:32:41"

  2. Get ProblemDetails

    • NOTE: A ProblemDetails response is the standard payload returned for non-200 HTTP Status code request to the API (excluding validation failures).

    • Locate GET - Returns a ProblemDetails response and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

    • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

      • HTTP/1.1 400 Bad Request

      • { "type": "BadHttpRequestException", "title": "Bad request.", "status": 400, "detail": "This is a dummy ProblemDetails response for testing purposes.", "instance": "/api/v1/hires/test/problem-details", "traceid": "0HN60H97DJD9A:00000558" }

  3. Get ValidationProblemDetails

    • NOTE: A ValidationProblemDetails response is the standard payload returned for a 422 HTTP status code which indicates the request was accepted, but the input failed validation for one or more reasons.

    • Locate GET - Returns a ValidationProblemDetails response and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

    • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

      • HTTP/1.1 422 Unprocessable Entity

      • { "type": "ValidationException", "title": "One or more validation errors occurred.", "status": 422, "detail": "This is a dummy ValidationProblemDetails response for testing purposes.", "instance": "/api/v1/hires/test/validation-problem-details", "errors": { "Property1": ["This is a validation failure message for Property 1."], "Property2": ["This is a validation failure message for Property 2."], "Property3": ["This is a validation failure message for Property 3."] }, "traceid": "0HN60H97DJD9A:00000565" }

Fetching some data

The first call you will want to perform is to return all the organsations associated to your user. This is important as the majoroty of the Hire API endpoints require an organisationId as an input.

The below tests are for the Organzations API group Check that Group by tag is on to ensure the endpoints are grouped by API route.

  1. Get Organisations

    • Locate GET - Retrieves the list of organisations and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

    • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

      • HTTP/1.1 200 OK

      • api-supported-versions: 1.0 content-length: 31 content-type: application/json; charset=utf-8; x-api-version=1 date: Tue, 20 Aug 2024 14:54:47 GMT request-context: appId=cid-v1:215275d3-db75-4b76-b46a-56bbc77314b1

      • [ { "id": 1, "name": "VMG Org 1"}, { "id": 2, "name": "VMG Org 2"} ]

The below tests are for the Hires API group Check that Group by tag is on to ensure the endpoints are grouped by API route.

  1. Get Vehicle Groups

    • Locate GET - Retrieves the list of vehicle groups and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

      • Provide an organisationId retrieved from the call to Get Organisations above.

    • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

      • HTTP/1.1 200 OK

      • [{ "Name": "S1", "CustomName": "A", "Description": "Standard", "PriceDaily": 29.24, "PriceKind": "Value", "ExampleVehicle": "Hyundai I10 3 door" }, { "Name": "S2", "CustomName": "B", "Description": "Standard", "PriceDaily": 31.72, "PriceKind": "Value", "ExampleVehicle": "Vauxhall Corsa 1.2 5 door" }, { "Name": "S3", "CustomName": "C", "Description": "Standard", "PriceDaily": 35.66, "PriceKind": "Value", "ExampleVehicle": "Ford Focus 1.0T" }]

  2. Get Vehicle Extras

    • Locate GET - Retrieves the list of hire extras and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

      • Provide an organisationId retrieved from the call to Get Organisations above.

    • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

      • HTTP/1.1 200 OK

      • [{ "Name": "Towbar", "PriceDaily": 7, "PriceKind": "Value" }, { "Name": "Estate", "PriceDaily": 4.5, "PriceKind": "Value" }, { "Name": "Automatic", "PriceDaily": 4.5, "PriceKind": "Value" }]

  3. Get Hires

    • NOTE: This will only return hires if they currently exists on the system for the current user.

    • Locate GET - Retrieves list of hire summaries and click the green Try It button.

    • A side bar will open up where you may have to select the Subscription Key to use if not already selected.

      • Provide an organisationId retrieved from the call to Get Organisations above.

      • Provide the PageNumber e.g. 2

      • Provide the PageSize e.g. 3

    • Click the red Send button at the bottom of the side bar and you should receive a response (like below)

      • HTTP/1.1 200 OK

      • { "PageNumber": 2, "PageSize": 3, "PageCount": 7, "ItemCount": 19, "HasPreviousPage": true, "HasNextPage": true, "IsOutOfRange": false, "Items": [{ "Id": "VMG-282", "ExternalReference": "123456", "CreatedAt": "2024-07-10T10:59:39+00:00", "UpdatedAt": "2024-07-10T10:59:45+00:00", "Status": "HireRequested", "HireKind": "DirectHire", "CustomerName": "Mr. Adrian Test", "VehicleGroup": "S1", "VehicleGroupCustomName": "A", "ActionsResponse": { "CanCancel": true, "CanChangeDates": true, "CanOffHire": false }, "HireStartDate": "2024-07-10T07:00:00+00:00", "HireEndDate": "2024-07-10T13:00:00+00:00" }, { "Id": "VMG-262", "ExternalReference": "1231", "CreatedAt": "2024-06-20T09:19:29+00:00", "UpdatedAt": "2024-06-20T09:19:35+00:00", "Status": "HireRequested", "HireKind": "DirectHire", "CustomerName": "Mr. Test Ticke", "VehicleGroup": "", "VehicleGroupCustomName": "A", "ActionsResponse": { "CanCancel": true, "CanChangeDates": true, "CanOffHire": false }, "HireStartDate": "2024-06-21T10:00:00+00:00", "HireEndDate": "2024-06-28T10:00:00+00:00" }, { "Id": "VMG-236", "ExternalReference": "BF_TEST", "CreatedAt": "2024-06-06T12:11:05+00:00", "UpdatedAt": "2024-06-06T12:12:36+00:00", "Status": "HireRequested", "HireKind": "DirectHire", "CustomerName": "Mr. Boguslaw Dirfc", "VehicleGroup": "S2", "VehicleGroupCustomName": "B", "ActionsResponse": { "CanCancel": true, "CanChangeDates": true, "CanOffHire": false }, "HireStartDate": "2024-06-07T06:00:00+00:00", "HireEndDate": "2024-06-09T06:00:00+00:00" }] }