Back to Blog

API Highlight: Services

In this post we’ll cover the service layout, how the different resources fit together to form a complete service and grab some live data on the service status.

If you haven’t read the introduction post to this series, I’d suggest starting there for some background. Let’s start by listing the services that I have access to.

# /secure/servicegroup/person/:personId
curl -X GET https://api-staging.megaport.com/secure/servicegroup/person/205?token=dafb8cd2-762a-4633-943b-7d5886c34124



[
    {
        "companyId": 203,
        "companyName": "MEGAPORT",
        "serviceGroupId": 122,
        "serviceGroupName": "Default",
        "services": [
            {
                "createDate": 1401747531149,
                "networkStatus": null,
                "provisioningStatus": "NEW",
                "serviceId": 501,
                "serviceName": "Test Service",
                "serviceType": "MEGAPORT",
                "speed": 10000,
                "terminateDate": null,
                "trialAgreement": true
            }
        ]
    }
]

So this information is useful, but it doesn’t tell me a lot about the service. It does give me the serviceId though, which we can use to grab the rest.

# /secure/technicalservice/:serviceId
curl -X GET https://api-staging.megaport.com/secure/technicalservice/501?token=dafb8cd2-762a-4633-943b-7d5886c34124

Before we dig in to the response for this query let’s have a look at the service model that the systems use internally.

At the lowest level we have resource objects. These are things like switch interfaces, IP addresses etc. Above that level we have a NetworkService; this is a model that represents the state of the network at any given time. At the top level we have a TechnicalService; this is the customer-facing construct and is what we present in the portal. The TechnicalService is how we refer to services from a support perspective and this is the item that we bill for.

With this information in hand, let’s take a look at the response.

{
    "adminContactId": null,
    "adminContactName": null,
    "billableId": 505,
    "billingContactId": null,
    "billingContactName": null,
    "companyId": 203,
    "companyName": "MEGAPORT",
    "components": [
        {
            "description": "The MEGAPORT at Global Switch",
            "jservice_id": 501,
            "nservice_id": 663,
            "resources": [
                {
                    "description": "MEGAPORT",
                    "groups": [
                        "Customer"
                    ],
                    "media": "LR",
                    "name": "Ethernet3/6",
                    "port_speed": 10000.0,
                    "resource_type": "interface"
                }
            ],
            "status": "Deployment",
            "type": "MEGAPORT"
        }
    ],
    "currentEstimatedDelivery": null,
    "name": "Test Service",
    "productType": "MEGAPORT",
    "provisioningItems": [],
    "provisioningStatus": "NEW",
    "rateType": "MONTHLY",
    "requestedDate": 1404050400000,
    "tags": [],
    "technicalContactId": null,
    "technicalContactName": null,
    "technicalServiceId": 501,
    "terminationDate": null,
    "trialAgreement": true,
    "vxcDistanceBand": null,
    "vxcPermitted": true
}

Here we have a lot of the same information as before but with new, key components. This contains a list of NetworkService objects that relate to the TechnicalService, each with its own list of resource objects. This service is a MEGAPORT on its own, which is fairly boring. Let’s look at one with a VXC.

{
    "adminContactId": null,
    "adminContactName": null,
    "billableId": 491,
    "billingContactId": null,
    "billingContactName": null,
    "companyId": null,
    "companyName": null,
    "components": [
        {
            "description": "VXC between The MEGAPORT at Equinix SY1/2 and The MEGAPORT at Global Switch",
            "jservice_id": 486,
            "nservice_id": 674,
            "resources": [
                {
                    "description": "MEGAPORT",
                    "groups": [
                        "Customer"
                    ],
                    "id": 1326.0,
                    "media": "LR",
                    "name": "Ethernet5/22",
                    "port_speed": 10000.0,
                    "resource_type": "interface"
                },
                {
                    "description": "MEGAPORT",
                    "groups": [
                        "Customer"
                    ],
                    "id": 1236.0,
                    "media": "LR",
                    "name": "Ethernet3/21",
                    "port_speed": 10000.0,
                    "resource_type": "interface"
                },
                {
                    "a_vlan": 999.0,
                    "b_vlan": 999.0,
                    "description": "VXC between The MEGAPORT at Equinix SY1/2 and The MEGAPORT at Global Switch",
                    "id": 113.0,
                    "name": "vll100115",
                    "rate_limit_mbps": 2000.0,
                    "resource_type": "vll"
                }
            ],
            "status": "Deployment",
            "type": "VXC"
        }
    ],
    "currentEstimatedDelivery": null,
    "name": "VXC",
    "productType": "VXC",
    "provisioningItems": [],
    "provisioningStatus": "NEW",
    "rateType": "MONTHLY",
    "requestedDate": 1401767799805,
    "tags": [],
    "technicalContactId": null,
    "technicalContactName": null,
    "technicalServiceId": 486,
    "terminationDate": null,
    "trialAgreement": true,
    "vxcDistanceBand": "METRO",
    "vxcPermitted": true
}

This one contains much the same thing but the NetworkService has a few more resources. A MEGAPORT with an attached IX would have two NetworkServices linked, both with their own list of resources. Right now we only have a picture of these services, not anything specific about the current status. Let’s dig a little deeper..

# /secure/nservice/:networkServiceId/logs
curl -s -X GET https://api-staging.megaport.com/secure/nservice/355/logs?token=dafb8cd2-762a-4633-943b-7d5886c34124



{
    "avg_delta": {          // average delta over the last 24 hours represented in Mbps
        "avg_in": 30.03,
        "avg_out": 140.07
    },
    "ix_status": {          // IX service: current status of BGP connections by resource_id
        "379": 1.0,
        "380": 1.0,
        "381": 0.0,
        "382": 0.0
    },
    "log": [                // recent events linked to the service
        {
            "count": 1.0,
            "event": "bgpUp",
            "message": "103.26.68.3: BGP session established to syd-gs-rs2",
            "resource_id": 380.0,
            "resource_type": "bgp_connection",
            "service_id": 355.0,
            "time": "2014-05-07 00:07:52.143889+00"
        },
        {
            "count": 1.0,
            "event": "bgpUp",
            "message": "103.26.68.3: BGP session established to syd-sy1-rs1",
            "resource_id": 379.0,
            "resource_type": "bgp_connection",
            "service_id": 355.0,
            "time": "2014-05-07 00:07:49.690467+00"
        },
        {
            "count": 1.0,
            "event": "bgpDown",
            "message": "103.26.68.3: BGP session closed to syd-gs-rs2",
            "resource_id": 380.0,
            "resource_type": "bgp_connection",
            "service_id": 355.0,
            "time": "2014-05-06 13:23:07.908485+00"
        },
        {
            "count": 1.0,
            "event": "bgpDown",
            "message": "103.26.68.3: BGP session closed to syd-sy1-rs1",
            "resource_id": 379.0,
            "resource_type": "bgp_connection",
            "service_id": 355.0,
            "time": "2014-05-06 13:22:59.633246+00"
        }
    ],
    "max_delta": {          // maximum delta over the last 24 hours represented in Mbps
        "max_in": 96.76,
        "max_out": 316.61
    },
    "peak24hrs": 3,         // peak service utilisation over the last 24 hours represented as a percentage
    "service_status": 1     // current service status (interface for MEGAPORT, VLL for VXC and BGP sessions for IX)
}

The output above is a current snapshot of the service state with some comments inline to explain.

These are all fairly simple examples picked out to demonstrate how easy it is to use our API to source information and generate reports on your account and the services linked. In the next post we’ll look at the ordering process and delve into the technical aspects of the service objects.