Standards

View API Docs

API standard

The standard AEMO uses for APIs is the OpenAPI Specification (OAS). For more details, see OpenAPI-Specification: https://github.com/OAI/OpenAPI-Specification.

Design Principles

The REST approach uses the features of HTTP to make requests using these design principles:

  1. HTTPS protocol provides services over MarketNet or the

  1. Resources are mapped to a location within a hierarchy of URIs, for example: service host/system/business_function.

    1. The root of the hierarchy represents the web service or API application and provides the resources

    2. The next level provides specific information about the resource,

    3. The final level provides data from the specific resource For more details, see URL format below.

  2. Accommodates a variety of payloads such as XML or JSON.

URL Format

API URLs are in the following format:

Parameter

Description

protocol

HTTPS

web service host

Name of the server hosting the service or an external proxy.

Business_function

API Name - The AEMO system providing the services, e.g. GeneratorRecall

Resource

Entities of the business function e.g. /listRecallPlans

?querystring parameters

Used in the GET Method

Examples:

Format Example

https://web service host/business_function/APIversion/resource?querystring parameters

Internet URL example

https://apis.prod.aemo.com.au:9319/ws/GeneratorRecall/1.0/listRecallPlans

MarketNet URL example

https://apis.prod.marketnet.net.au:9319/ws/GeneratorRecall/1.0/listRecallPlans

Headers

Header Parameters

Description

Allowed values/Example

Content-type

HTTPS request format.

Content-type: application/json

Accept

HTTPS response format.

Accept: application/json

Content-length

Content length of file. The value is populated when the request is sent.

Content-length: nnn

X-initiatingParticipantID

The participant ID

X-initiatingParticipantID: 123456

X-market

The market type that the request applies.

X-market: GAS

Authorization

Specifies basic HTTP authentication containing the Base64[1] encoded username and password. The participant’s URM username and password are concatenated with a colon separator and then Base64 encoded.

Authorisation: Basic QFhQVC0wMDAwMzoyZWRmOGJhYS0wY2I0LTQwZjctOTIyMS0yODUxNmM4N2MxNjQ= (For URM username “@XPT-00003” and password “2edf8baa-0cb4-40f7-9221-28516c87c164”)

Methods

HTTPS method

Operation

Details

GET

Retrieve Data

The GET method has the query string parameters in the URL.

The GET method does not have the Content-Type passed in the HTTP request.

Not all AEMO's APIs use the GET method.

POST

Post Data

The POST method has:

  • No query string parameters in the URL.

  • BASIC Authentication details, username and password encoded and passed in the request header.

  • HTTP request header parameters specific to the API (if any).

  • Payload Example:

{

"ParticipantId":"PID",

"StartDate":"2017-11-01T00:00:00+10:00", "EndDate":"2017-11-02T00:00:00+10:00",

"StationId":"PID6",

"DUID":"AEMO1",

"OutagePlanId":"MMS_GEN_OUT1"

}

DELETE

Delete Data

The DELETE method has the query string parameters in the URL.

HTTP Response Codes

The HTTP Response has:

  • A response code and description, with

    • A successful request indicated by 200

    • Other response codes for technical and Payload validation

  • Optional Payload

Status Codes

The e-Hub sends an appropriate HTTP response code and response Payload when any of the technical validations fail.

Code

Condition

Description

200

Indicates a successful request.

OK

400

Invalid API URI

The service cannot be found for the endpoint reference (EPR), URI, "Fault": "SystemMessageExceptionDump"

401

Invalid credentials

No BASICAuth information in HTTP Request Header

Unauthorized

"Exception": "Unauthorized:Invalid UserName or Password"

404

Resource not Found

"Exception": "Resources for the endpoint URI not found. Endpoint

URI: Resource"

405

Invalid Method used (e.g. GET used instead of POST)

"Exception": "Input request HTTP method is Invalid Method passed but operation (Resourse Name) accepts only: (vValid Method)"

422

Business validation failure

Unprocessable entity

429

Exceeds Throttling Limits

"Exception": "Number of inbound requests exceeded the throttling limits; try after some time"

500

e-Hub is operational but downstream systems are not available or malformed payload (JSON)

"Exception": "Application Unavailable"

Traffic management

To protect the backend service from overload, AEMO's API Platform enforces traffic limits. For details about the traffic limits for each individual API, see the individual API policy.

Connection and read timeout settings

We recommend participants use the following settings when calling AEMO’s APIs.

Type

Problem

Recommended settings

Connection timeout

Cannot connect to the e-Hub’s endpoint (e.g. e-Hub infrastructure is not available).

10 seconds

Read timeout

Connected to the endpoint but the e-Hub does not respond within the configured time.

30 seconds

Glossary

Abbreviation/Term

Explanation

API Gateway

The gateway on AEMO’s side providing participant communication options, accessible over the internet or MarketNet. It uses resources and methods to push messages to Participants’ API Gateways

API

Application Programming Interface; a set of clearly defined methods of communication between various software components.

API Portal

Where you can view available APIs, view API documentation (including OpenAPI Specs) and obtain Postman collections.

CSR

Certificate Signing Request is a block of encoded text given to a Certificate Authority when applying for an TLS Certificate. It also contains the Public Key to include in the certificate. Usually, a Private Key is created at the same time, making a Key Pair.

eHub

Consists of the API Portal and the API Gateway for both electricity and gas.

JSON

JavaScript Object Notation

Key Pair

TLS uses a technique called public-key cryptography, based on the concept of a Key Pair. The Key Pair consists of encrypted Public and Private Key data. It is only possible to decrypt the Public Key with the corresponding Private Key.

MarketNet

AEMO’s private data network connection.

MSATS

Retail Market Settlement and Transfer System

OAS

OpenAPI Specification

Participant API Gateway

The interface implemented by participants where AEMO’s API pushes messages.

Participant ID

Registered participant identifier

Payload

The data sent by a POST request. The Payload sections sits after the header.

PID

Participant ID

Private Key

The secret Private Key is a text file used initially to generate a Certificate Signing Request (CSR), and later to secure and verify connections.

Public Key

The Public Key is included as part of your TLS certificate, and works together with your Private Key to make sure your data is encrypted, verified, and not tampered with. Anyone with access to the Public Key (i.e. the certificate) can verify the digital signature is authentic without having to know the secret Private Key.

SOAP

Simple Object Access Protocol

Swagger file

The OpenAPI Specification (OAS) definition of the API.

TLS

Transport Layer Security, cryptographic protocol providing API communication security.

WSDL

Web Services Description Language

XML

Extensible Markup Language