MIP SDK

Quickstart

You are recommended to set up a small separate system for development.

Requirements

To set up a small development system, you'll need:

A Milestone account (for downloading software installers and requesting licenses)
An XProtect VMS Products installer (2022 R1 or later)
An XProtect VMS license file

To deploy the system with certificates, you'll need:

The fully qualified domain name of the development system
A server certificate for the development system

Refer to Milestone product system requirements for more information about system requirements.

If you have previously installed the 2021 R2 pre-release of the API Gateway, you'll have to uninstall the pre-release before proceeding.

Installing XProtect

This is a brief walkthrough of the installation of a simple development system with all system components on the same host. Learn more.

If you have already set up a system with XProtect VMS 2022 R1 or later, you can skip to Verify installation.

1. Get a Milestone account

If you don't already have a Milestone account, go to Sign up to the Milestone Portal to request an account.

2. Get an XProtect license file

You can request a free 30-day trial license, or get test licenses as a Milestone Technology Partner. Learn more.

3. Create a server certificate (optional)

Create and install a server certificate. When prompted for DNS names, include the fully qualified domain name for the server. Learn more.

You should consider setting up a server certificate and using HTTPS. While the IDP, the API Gateway, and the management server all can work with either HTTP or HTTPS, production systems should be set up with server certificates. User credentials, bearer tokens, and other sensitive data are transmitted in cleartext if you don't set up certificates and use HTTPS.

4. Download XProtect VMS Products installer

Download an XProtect VMS Products installer from the software download page.

5. Install XProtect

Run the installer you just downloaded:

When you get to the Select an installation type page, select Single computer.
When you get to the Select encryption page, enable Server certificate and select the VMS SSL Certificate you created and installed in step 1.
When you get to the Add users page, add a Basic user with the Administrators role, for example user seamrune with password Rad23Swops#.

6. Verify installation

Make sure that the API Gateway is operational and reachable.

curl --insecure --request GET "https://test-01.example.com/api/.well-known/uris"

This assumes that you will set up a server certificate and use HTTPS. If you chose to not create and use a server certificate, replace https with http in all instructions.

7. Create a user

Use the XProtect Management Client to create an XProtect Basic user with administrator rights. Learn how.

8. Get a token

Replace the hostname test-01.example.com, username seamrune, and password Rad23Swops# in the following code samples.

curl --insecure --request POST "https://test-01.example.com/API/IDP/connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=password" \
--data-urlencode "username=seamrune" \
--data-urlencode "password=Rad23Swops#" \
--data-urlencode "client_id=GrantValidatorClient"

Response body

{
    "access_token": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L . . . ay0ferTwm-DZ4OxNXGTHk5t7R_YTWPjg",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "managementserver"
}

In Windows Command Prompt (CMD), replace the line continuation character \ with ^.

9. Your first API request

Replace the hostname test-01.example.com and the bearer token value eyJhbG . . . YTWPjg in the following code samples.

curl --insecure --request GET "https://test-01.example.com/api/rest/v1/sites" \
--header "Authorization: Bearer eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L . . . ay0ferTwm-DZ4OxNXGTHk5t7R_YTWPjg"

Response body

{
    "array": [
        {
            "displayName":"TEST-01",
            "id":"2d12465c-3485-4ca8-a9fb-86a79de1a82f",
            "name":"TEST-01",
            "description":"",
            "lastModified":"2021-11-11T11:11:11.1111111Z",
            "timeZone":"Central Europe Time",
            "computerName":"TEST-01",
            "domainName":"example.com",
            "lastStatusHandshake":"2021-11-11T11:11:11.1111111Z",
            "physicalMemory":0,
            "platform":"[Not Available]",
            "processors":0,
            "serviceAccount":"S-1-5-20",
            "synchronizationStatus":0,
            "masterSiteAddress":"",
            "version":"22.1.0.1",
            "relations": {
                "self": {
                    "type":"sites",
                    "id":"2d12465c-3485-4ca8-a9fb-86a79de1a82f"
                }
            }
        }
    ]
}

In Windows Command Prompt (CMD), replace the line continuation character \ with ^.