API Highlight: Introduction

One of the key features of the Megaport service is our flexible network model. The core of the system is the Megaport API and over the coming months we’ll be doing a series of posts around the API with some usage information and examples.

Architecture

The software stack was designed to be modular, allowing us to easily add and remove layers while maintaining a consistent customer experience. One of the key points here for the technical team was to add a layer of abstraction between the network equipment and the management software. Initially this means we’re not locked in to a specific vendor but longer term it means that even moving to a new technology like OpenFlow can be achieved by adding a new module at the Agents layer while the rest of the stack remains the same. As can be seen in the stack, the Megaportal and our phone apps are all dependent on the RESTful API to talk to our backend systems. The intention here is that we use the same interface and mechanisms internally that we expose to customers.

Using the API

There are some useful browser extensions for working with RESTful APIs. Let’s start with something simple and authenticate. If you’d like to follow on with the examples you’ll need to make sure you replace the example credentials.

# Python can be used to format the JSON output if installed 
# | python -mjson.tools 
curl -X POST  
   -d 'username=example&password=secret'  
   https://api-staging.megaport.com/login

Once we authenticate, we’re presented with an object that contains information about the user and the session token we’ll need later.

{
    "channelPartner": false,
    "companyId": 203,
    "companyName": "MEGAPORT",
    "expiryDate": null,
    "language": "English",
    "locale": "Australia",
    "loginDate": 1400643699384,
    "permissions": {
        "203": [
            "services",
            "approve_order",
            "tools",
            "notifications",
            "company_admin",
            "financials",
            "place_order",
            "virtual_employee",
            "tickets",
            "graphs"
        ]
    },
    "personId": 205,
    "session": "dafb8cd2-762a-4633-943b-7d5886c34124",
    "sourceIp": "10.3.1.119",
    "timeZone": "1000",
    "userAgent": "curl/7.30.0",
    "username": "example"
}

In this example you can see who the user is and what permissions they hold. With our [Service Agents] feature a single user account can have permissions under multiple companies. The permissions property will contain a list for each company the user account has access to. The session value contains the token that you’ll need for each subsequent request. Then we can list some information about the company that the user belongs to:

# /secure/party/company/:companyId 
curl -X GET https://api-staging.megaport.com/secure/party/company/203?token=dafb8cd2-762a-4633-943b-7d5886c34124 

Conclusion

In the next post we’ll discuss the service construct and how to work with the Megaport API to report on services and get the related technical resources. If there are any specific things you’d like to see please let us know in the comments and we’ll do our best to cover it in a future writeup.