SDK Access

This window enables you or a third-party vendor to review the APIClosed Application Programming Interface. credentials that your site needs to use the Neptune® 360™ APIs. It displays information about:

The window also enables you to download a YAMLClosed Yaml Ain't Markup Language. YAML is a human-friendly data serialization standard for all programming languages. file for a bundle. You can upload a YAML file into a RESTful APIClosed An API that uses HyperText Transfer Protocol (HTTP) requests to GET, PUT, POST and DELETE data. A RESTful API is based on representational state transfer (REST) technology, an architectural style and approach to communications often used in web services development. editor or client to visualize the SDKClosed Software Development Kit. A collection of software development tools in one installable package. An SDK is typically specific to a hardware platform and operating system combination. for a certain bundle. Third party vendors have their own Neptune 360 accounts for their developers. When those users log in, they see their own set of keys needed to use the APIs for the utilities they manage.

 

Up arrow - go to top of topic

 

The Neptune APIs enable developers and third-party users within your utility to access Neptune 360 Web services. The services allow you to download utility data from AWS, which is the Neptune 360 host system. Utilities and third-party vendors that have access to multiple utilities may have access to varied APIs.

The following APIs are included with the Advanced subscription:

  • Tokens – returns a bearer token required for authenticating the user and calling other web services. A bearer token is valid for 10 minutes following authentication.
  • Endpoints – returns a list and details of claimed endpointsClosed Any meter or Meter Interface Unit (MIU) that collects usage data. for a utility.
  • Last Readings – returns last readings for a utility’s endpoints.
  • Readings – returns captured readings within a date range for a utility’s endpoints. It returns the latest reading within each hour.
  • Consumption – returns consumption history within a date range for a utility’s endpoints.
  • Gateways – returns gateways and collectors for a utility. It also returns the count for the MIU "heard" for each gateway and collector and the related sync times.

For more detailed information about the APIs, see the Neptune 360 API Reference Guide.

What You Can See and Do in This Window

Click a link to display the related information or step-by-step procedure.

Action Options

 

Up arrow - go to top of topic

 

View the SDK Access Window

The summary section of the SDK Access window shows your Client Secret key, API key, and contact information. The keys are required for using the API that requests the authentication tokens from AWS. The Neptune 360 technical support team assigns your keys.

Image shows the SDK Access window that includes access details such as Client Secret Key, API Key, and contact information in the summary section. The grid section includes utility details such as the utility name, site ID, client ID, the bundle the utility is permitted to use, the date the bundle was created, and a Download button to download the YAML file and other tools to create APIs.

 

Important! Do not disclose your keys to any other party. If you want another party to have access to your permitted bundles, email support@neptunetg.com to have separate keys created for that party.

Also, email support@neptunetg.com to update any of your contact information.

 

Up arrow - go to top of topic

 

View the Grid

Each row in the grid shows a bundle that the site is permitted to use plus the following information:

  • Utility – utility for the bundle that the featured site has access to use. Third-party vendors see more bundles in the grid, because they work with multiple utilities.
  • Site ID – identifier for the utility. This ID appears on various windows in Neptune 360.
  • Bundle – bundle name that the site has access to use.
  • SDK – button to access to the YAML file and other tools to create APIs.
  • Client ID – tapping Show reveals the client ID for the bundle.
  • Created Date – date and time the bundle was created.

If you have access to multiple utilities and bundles, you can customize the grid view.

 

Up arrow - go to top of topic

 

Open a YAML File Using Swagger

This section describes how to open a YAML file using Swagger Editor. You can open a YAML file using a RESTFul API or any other client or editor you choose.

  1. In your browser, go to https://editor.swagger.io/ to open the Swagger interface.
  2. In the SDK column of the SDK Access window, click Download to download the YAML file for a specific bundle.
  3. In the resulting dialog, click Save to save the YAML file on your computer.
  4. In Swagger, click File, and then click Import File to open the YAML file.

Once the file is imported, Swagger displays available APIs on the right side of the window. If you select an API, it expands and shows the inputs plus an example output.

Image shows an example YAML file with a list of APIs in the right panel. You can click the GET button for an API to display the API inputs plus an example output in the left panel.

 

Up arrow - go to top of topic

 

Request a Token

You need an authentication token to use Neptune 360 APIs.

Important! Each token expires after 10 minutes. You can call /token again to receive a new token.

 

  1. Call the /token web service using your API key, client secret key, and client ID for a particular bundle to receive a token for that bundle.

When you receive a token for a bundle, any permitted web service in that bundle requires that token to be used as a header key.

  1. Use the authorization header key and add "Bearer" before the token type for the authorization key value.

Example: Bearer [token]

Token Usage

If you make more API requests within a given week than your plan allows, Neptune 360 displays a 429 error:

  • Status – 429–Too Many Requests.
  • Content – {"message":"Limit Exceeded"}.
Important! Your request count resets each week. Email Customer Support at support@neptunetg.com to change your usage plan and increase or decrease your request count.

 

Up arrow - go to top of topic

 

Neptune logo indicates the end of the Help topic