Developer Guide for the IPSignature 3 API

This guide includes help for developers targeting the IPSignature 3 API. It is intended to give an overview of the API features, the expected order of calls and any other business rules associated with the API. To see the full details for each API method and test those methods, see the APIs section.

Only registered and approved users of the Globanet website may access the API. If you do not already have a website account you must first register using the following sites:

https://globalnet.satcomglobal.com (production website)

https://gntest.satcomglobal.com    (test website)

This registration should be in place before attempting to register and subscribe for API access as described below.

Registration, Subscription, and Authorisation

All developer users must register to use the API features. Registration is described in the Developer Guide. To use the IPSignature 3 API you need an active subscription to the Globalnet product. The subscription process is described in the Developer Guide. Authorisation for the IPSignature 3 API requires you to supply your subscription key in the HTTP request header:

Ocp-Apim-Subscription-Key: your-subscription-key

Glossary of API Resource Names

Within the IPSignature 3 API, the following names are used to describe resources in the system:

Company: a client company. Used as a container for ships and users.
Ship: a location where the IPSignature 3 software is installed.
User group: a grouping for IPSignature 3 user accounts.
User: IPSignature 3 user account with associated email address.

Hierarchy of items in the system: Ships items are owned by a company. Companies may own zero or more user groups. User groups contain zero or more user accounts.

Note: in the examples shown throughout this page the URI path prefix is omitted . This might be for example:

https://sg-apim-rn.azure-api.net/ipsignature-uat/api/v1    (test environment)

https://sg-apim-rn.azure-api.net/ipsignature/api/v1        (production environment)

The API details section shows the full URI for each request.

Data Access Controls

The data available to each API user is controlled by their configured user account. When authenticating with the API, the client application supplies an API key (as described elsewhere), this key maps to a user in the Globalnet system. Each user is configured for access to one or more IPSignature companies in the system and their associated ships and users. Queries against the API listing methods all take a companyId filter parameter which must be set. For example:

// Get users for company Id 12345
GET /users?companyId=12345

To list the IPSignature companies accessible to the current login use:

GET companies

Example response:

[
    {
        "Id": 1,
        "Name": "Test Ship Management Company"
    },
    {
        "Id": 2,
        "Name": "Satcom Global"
    },
...]

Companies

List Companies

List companies accessible by the current user:

GET /companies

Example response: see above.

Get Company Details

Details for an equipment item are retrieved using the equipment Id or ICCID of the item:

// get company by unique Id
GET /companies/{id}
e.g.
GET /companies/1

Example response:

{
    "Id": 1,
    "Name": "Test Ship Management Company"
}

Ships

To view the list of ships for a given company use the following call:

GET /ships?companyId={company-id}

This call takes an mandatory companyIdfilter.

Example response:

[
    {
        "Id": 1,
        "Name": "Test Vessel 1",
        "InstallationGuid": "11223344-0000-1111-2222-333344445555",
        "CompanyId": 1,
        "CompanyName": "Test Ship Management Company",
        "SatelliteTerminalId": 3,
        "SatelliteTerminalName": "Inmarsat FBB"
    },
...]

Ship details are available using the call:

GET /ships/{id}

This gives ship details as per the listing method shown above.

User Groups

To the list of user groups in a company use the following call:

GET /usergroups?companyId={company-id}

This call takes an mandatory companyId filter.

Example response:

[
    {
        "Id": 1,
        "Name": "Crew"
    },
    {
        "Id": 2,
        "Name": "Business"
    },
    {
        "Id": 3,
        "Name": "Charterers"
    }
]

Details for an individual user group are available using the call:

GET /usergroups/{id}

This gives user group details as per the listing method shown above.

Users

To the list of users in a company use the following call:

GET /users?companyId={company-id}

This call takes an mandatory companyId filter.

Example response:

[
    {
        "Id": 2,
        "Name": "TEST_002",
        "Email": "test_002@ipsignature3.net",
        "Password": "123456789",
        "DeliveryReceipts": false,
        "IsOnShoreLeave": false,
        "CompanyId": 1,
        "CompanyName": "Test Ship Management Company",
        "ShipId": 1,
        "ShipName": "Test Vessel 1",
        "ShipInstallationGuid": "11223344-0000-1111-2222-333344445555",
        "UserGroupId": 2,
        "UserGroupName": "Business"
    },
...]

User Details

Details for an individual user are available using the call:

GET /users/{id}

This gives user details as per the listing method shown above.

Create New User Account

To create a new user account use the following request:

POST /users

Example request body:

{
    "Name": "NEWUSER_001",
    "Email": "newuser_001@ipsignature3.net",
    "Password": "123456789",
    "CompanyId": 1,
    "ShipId": 1,
    "UserGroupId": 2
}

The new user's name and email address must be unique within the IPS3 system. If a duplicate name or email address are used an HTTP response 400 "Bad Request" is returned with details of the problem. The new user details will be returned upon successful creation of the user, with an HTTP response code 201 "Created".

Update User Account

To update an existing user account use the following request:

PUT /users/{id}

Example request body:

{
    "Id": {id}
    "Name": "UPDATEDUSER_001",
    "Email": "updateduser_001@ipsignature3.net",
    "Password": "123456789",
    "CompanyId": 1,
    "ShipId": 1,
    "UserGroupId": 2
}

The updated user details will be returned, with an HTTP response code 200 "OK".

Delete User Account

To delete an existing user account use the following request:

DELETE  /users/{id}

The HTTP response code 200 "OK" indicates the user account has been deleted.