sdk-java

pkg:maven/com.m3ter/sdk-java@0.5.0

Used in: 0 components

Overview
Overview

Versions
Versions

Dependents
Dependents

Dependencies
Dependencies

Overview

Description

If you are using Postman, you can: - Use the **Download** button above to download the m3ter Open API spec JSON file and then import this file as the **m3ter API Collection** into your Workspace. See [Importing the m3ter Open API](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-open-api) in our main user Documentation for details. - Copy this link: [m3ter-Template API Collection](https://www.datocms-assets.com/78893/1672846767-m3ter-template-api-collection-postman_collection.json) and use it to import the **m3ter-Template API Collection** into your Workspace. See [Importing the m3ter Template API Collection](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-template-api-collection) in our main user Documentation for details. --- # Introduction The m3ter platform supports two HTTP-based REST APIs returning JSON encoded responses: - The **Ingest API**, which you can use for submitting raw data measurements. _(See the [Submit Measurements](https://www.m3ter.com/docs/api#tag/Measurements/operation/SubmitMeasurements) endpoint in this API Reference.)_ - The **Config API**, which you can use for configuration and management. _(All other endpoints in this API Reference.)_ ## Authentication and Authorization Our APIs use an industry-standard authorization protocol known as the OAuth 2.0 specification. OAuth2 supports several grant types, each designed for a specific use case. m3ter uses the following two grant types: - **Authorization Code**: Used for human login access via the m3ter Console. - **Client Credentials**: Used for machine-to-machine communication and API access. Complete the following flow for API access: 1. **Create a Service User and add Permissions**: Log in to the m3ter Console, go to **Settings**, **Access** then **Service Users** tab, and create a Service User. To enable API calls, grant the user **Administrator** permissions. 2. **Generate Access Keys**: In the Console, open the _Overview_ page for the Service User by clicking on the name. Generate an **Access Key id** and **Api Secret**. Make sure you copy the **Api Secret** because it is only visible at the time of creation. See [Service Authentication](https://www.m3ter.com/docs/guides/authenticating-with-the-platform/service-authentication) for detailed instructions and an example. 3. **Obtain a Bearer Token using Basic Auth**: We implement the OAuth 2.0 Client Credentials Grant authentication flow for Service User Authentication. Submit a request to the m3ter OAuth Client Credentials authentication flow, using your concatenated **Access Key id** and **Api Secret** to obtain a Bearer Token for your Service User. _See examples below._ 4. **Bearer Token Usage**: Use the HTTP 'Authorization' header with the bearer token to authorise all subsequent API requests. > Warning: The Bearer Token is valid for 18,000 seconds or 5 hours. When the > token has expired, you must obtain a new one. Below are two examples for obtaining a Bearer Token using Basic Auth: the first in cURL and the second as a Python script. ### cURL Example 1. Open your terminal or command prompt. 2. Use the following `cURL` command to obtain a Bearer Token: ```bash curl -X POST https://api.m3ter.com/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -u your_access_key_id:your_api_secret \ -d 'grant_type=client_credentials' ``` Replace `your_access_key_id` and `your_api_secret` with your actual **Access Key id** and **Api Secret**. 3. Run the command, and if successful, it will return a JSON response containing the Bearer Token. The response will look like this: ```json { "access_token": "your_bearer_token", "token_type": "Bearer", "expires_in": 18000 } ``` You can then use the Bearer Token _(the value of `"access_token"`)_ for subsequent API calls to m3ter. ### Python Example 1. Install the `requests` library if you haven't already: ```bash pip install requests ``` 2. Use the following Python script to obtain a Bearer Token: ```python import requests import base64 # Replace these with your Access Key id and Api Secret access_key_id = 'your_access_key_id' api_secret = 'your_api_secret' # Encode the Access Key id and Api Secret in base64 format credentials = base64.b64encode(f'{access_key_id}:{api_secret}'.encode('utf-8')).decode('utf-8') # Set the m3ter token endpoint URL token_url = 'https://api.m3ter.com/oauth/token' # Set the headers for the request headers = { 'Authorization': f'Basic {credentials}', 'Content-Type': 'application/x-www-form-urlencoded' } # Set the payload for the request payload = { 'grant_type': 'client_credentials' } # Send the request to obtain the Bearer Token response = requests.post(token_url, headers=headers, data=payload) # Check if the request was successful if response.status_code == 200: # Extract the Bearer Token from the response bearer_token = response.json()['access_token'] print(f'Bearer Token: {bearer_token}') else: print(f'Error: {response.status_code} - {response.text}') ``` Replace `your_access_key_id` and `your_api_secret` with your actual **Access Key id** and **Api Secret**. 3. Run the script, and if successful, it will print the Bearer Token. You can then use this Bearer Token for subsequent API calls to m3ter. ## Submitting Personally Identifiable Information (PII) **IMPORTANT!** Under the [Data Processing Agreement](https://www.m3ter.com/docs/legal/dpa), the only fields permissible for use in submitting any of your end-customer PII data in m3ter are the `name`, `address`, and `emailAddress` fields on the **Account** entity - see the details for [Create Account](https://www.m3ter.com/docs/api#operation/PostAccount). See also section 4.2 of the [Terms of Service](https://www.m3ter.com/docs/legal/terms-of-service). ## Rate and Payload Limits ### Config API Request Rate Limits See [Config API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits). ### Data Explorer API Request Rate Limits See [Data Explorer Request Rate Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits#date-explorer-request-rate-limits). ### Ingest API Request Rate and Payload Limits See [Ingest API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/ingest-api-limits) for more information. ## Pagination **List Endpoints** API endpoints that have a List resources request support cursor-based pagination - for example, the `List Accounts` request. These List calls support pagination by taking the two parameters `pageSize` and `nextToken`. The response of a List API call is a single page list. If the `nextToken` parameter is not supplied, the first page returned contains the newest objects chronologically. Specify a `nextToken` to retrieve the page of older objects that occur immediately after the last object on the previous page. Use `pageSize` to limit the list results per page, typically this allows up to a maximum of 100 or 200 per page. **Search Endpoints** API endpoints that have a Search resources request support cursor-based pagination - for example, the `Search Accounts` request. These Search calls support pagination by taking the two parameters `pageSize` and `fromDocument`. The response of a Search API call is a single page list. If the `fromDocument` parameter is not supplied, the first page returned contains the newest objects chronologically. Specify a `fromDocument` to retrieve the page of older objects that occur immediately after the last object on the previous page. Use `pageSize` to limit the list results per page, typically this allows up to a maximum of 100 or 200 per page. Default is 10. ## API Quick Start See [Getting Started with API Calls](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls) for detailed guidance on how to use our API to: - Create a Service User and add permissions. - Generate access keys for the Service User. - Use basic authentication to obtain a Bearer Token. For further guidance, also see [Creating and Configuring Service Users](https://www.m3ter.com/docs/guides/organization-and-access-management/managing-users/creating-and-configuring-service-users). ## Other Languages If you want to work with the m3ter REST APIs using other languages such as: - Python - JavaScript - C++ Please see the [Developer Tools](https://www.m3ter.com/docs/guides/developer-tools) topic in our main documentation for information about available SDKs. # Authentication

Snippets

<dependency>
    <groupId>com.m3ter</groupId>
    <artifactId>sdk-java</artifactId>
    <version>0.5.0</version>
</dependency>

Maven POM File

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <!-- This module was also published with a richer model, Gradle metadata,  -->
  <!-- which should be used instead. Do not delete the following line which  -->
  <!-- is to indicate to Gradle or any Gradle module metadata file consumer  -->
  <!-- that they should prefer consuming it instead. -->
  <!-- do_not_remove: published-with-gradle-metadata -->
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.m3ter</groupId>
  <artifactId>sdk-java</artifactId>
  <version>0.5.0</version>
  <name>m3ter API</name>
  <description>If you are using Postman, you can:

- Use the **Download** button above to download the m3ter Open API spec JSON
  file and then import this file as the **m3ter API Collection** into your
  Workspace. See
  [Importing the m3ter Open API](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-open-api)
  in our main user Documentation for details.
- Copy this link:
  [m3ter-Template API Collection](https://www.datocms-assets.com/78893/1672846767-m3ter-template-api-collection-postman_collection.json)
  and use it to import the **m3ter-Template API Collection** into your
  Workspace. See
  [Importing the m3ter Template API Collection](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls#importing-the-m3ter-template-api-collection)
  in our main user Documentation for details.

---

# Introduction

The m3ter platform supports two HTTP-based REST APIs returning JSON encoded
responses:

- The **Ingest API**, which you can use for submitting raw data measurements.
  _(See the
  [Submit Measurements](https://www.m3ter.com/docs/api#tag/Measurements/operation/SubmitMeasurements)
  endpoint in this API Reference.)_
- The **Config API**, which you can use for configuration and management. _(All
  other endpoints in this API Reference.)_

## Authentication and Authorization

Our APIs use an industry-standard authorization protocol known as the OAuth 2.0
specification.

OAuth2 supports several grant types, each designed for a specific use case.
m3ter uses the following two grant types:

- **Authorization Code**: Used for human login access via the m3ter Console.
- **Client Credentials**: Used for machine-to-machine communication and API
  access.

Complete the following flow for API access:

1. **Create a Service User and add Permissions**: Log in to the m3ter Console,
   go to **Settings**, **Access** then **Service Users** tab, and create a
   Service User. To enable API calls, grant the user **Administrator**
   permissions.
2. **Generate Access Keys**: In the Console, open the _Overview_ page for the
   Service User by clicking on the name. Generate an **Access Key id** and **Api
   Secret**. Make sure you copy the **Api Secret** because it is only visible at
   the time of creation.

See
[Service Authentication](https://www.m3ter.com/docs/guides/authenticating-with-the-platform/service-authentication)
for detailed instructions and an example.

3. **Obtain a Bearer Token using Basic Auth**: We implement the OAuth 2.0 Client
   Credentials Grant authentication flow for Service User Authentication. Submit
   a request to the m3ter OAuth Client Credentials authentication flow, using
   your concatenated **Access Key id** and **Api Secret** to obtain a Bearer
   Token for your Service User. _See examples below._

4. **Bearer Token Usage**: Use the HTTP 'Authorization' header with the bearer
   token to authorise all subsequent API requests.

&gt; Warning: The Bearer Token is valid for 18,000 seconds or 5 hours. When the
&gt; token has expired, you must obtain a new one.

Below are two examples for obtaining a Bearer Token using Basic Auth: the first
in cURL and the second as a Python script.

### cURL Example

1. Open your terminal or command prompt.
2. Use the following `cURL` command to obtain a Bearer Token:

```bash
curl -X POST https://api.m3ter.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -u your_access_key_id:your_api_secret \
  -d 'grant_type=client_credentials'
```

Replace `your_access_key_id` and `your_api_secret` with your actual **Access Key
id** and **Api Secret**.

3.  Run the command, and if successful, it will return a JSON response
    containing the Bearer Token. The response will look like this:

```json
{
  "access_token": "your_bearer_token",
  "token_type": "Bearer",
  "expires_in": 18000
}
```

You can then use the Bearer Token _(the value of `"access_token"`)_ for
subsequent API calls to m3ter.

### Python Example

1. Install the `requests` library if you haven't already:

```bash
pip install requests
```

2. Use the following Python script to obtain a Bearer Token:

```python
import requests
import base64

# Replace these with your Access Key id and Api Secret
access_key_id = 'your_access_key_id'
api_secret = 'your_api_secret'

# Encode the Access Key id and Api Secret in base64 format
credentials = base64.b64encode(f'{access_key_id}:{api_secret}'.encode('utf-8')).decode('utf-8')

# Set the m3ter token endpoint URL
token_url = 'https://api.m3ter.com/oauth/token'

# Set the headers for the request
headers = {
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/x-www-form-urlencoded'
}

# Set the payload for the request
payload = {
    'grant_type': 'client_credentials'
}

# Send the request to obtain the Bearer Token
response = requests.post(token_url, headers=headers, data=payload)

# Check if the request was successful
if response.status_code == 200:
    # Extract the Bearer Token from the response
    bearer_token = response.json()['access_token']
    print(f'Bearer Token: {bearer_token}')
else:
    print(f'Error: {response.status_code} - {response.text}')
```

Replace `your_access_key_id` and `your_api_secret` with your actual **Access Key
id** and **Api Secret**.

3. Run the script, and if successful, it will print the Bearer Token. You can
   then use this Bearer Token for subsequent API calls to m3ter.

## Submitting Personally Identifiable Information (PII)

**IMPORTANT!** Under the
[Data Processing Agreement](https://www.m3ter.com/docs/legal/dpa), the only
fields permissible for use in submitting any of your end-customer PII data in
m3ter are the `name`, `address`, and `emailAddress` fields on the **Account**
entity - see the details for
[Create Account](https://www.m3ter.com/docs/api#operation/PostAccount). See also
section 4.2 of the
[Terms of Service](https://www.m3ter.com/docs/legal/terms-of-service).

## Rate and Payload Limits

### Config API Request Rate Limits

See
[Config API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits).

### Data Explorer API Request Rate Limits

See
[Data Explorer Request Rate Limits](https://www.m3ter.com/docs/guides/m3ter-apis/config-api-limits#date-explorer-request-rate-limits).

### Ingest API Request Rate and Payload Limits

See
[Ingest API Limits](https://www.m3ter.com/docs/guides/m3ter-apis/ingest-api-limits)
for more information.

## Pagination

**List Endpoints** API endpoints that have a List resources request support
cursor-based pagination - for example, the `List Accounts` request. These List
calls support pagination by taking the two parameters `pageSize` and
`nextToken`.

The response of a List API call is a single page list. If the `nextToken`
parameter is not supplied, the first page returned contains the newest objects
chronologically. Specify a `nextToken` to retrieve the page of older objects
that occur immediately after the last object on the previous page.

Use `pageSize` to limit the list results per page, typically this allows up to a
maximum of 100 or 200 per page.

**Search Endpoints** API endpoints that have a Search resources request support
cursor-based pagination - for example, the `Search Accounts` request. These
Search calls support pagination by taking the two parameters `pageSize` and
`fromDocument`.

The response of a Search API call is a single page list. If the `fromDocument`
parameter is not supplied, the first page returned contains the newest objects
chronologically. Specify a `fromDocument` to retrieve the page of older objects
that occur immediately after the last object on the previous page.

Use `pageSize` to limit the list results per page, typically this allows up to a
maximum of 100 or 200 per page. Default is 10.

## API Quick Start

See
[Getting Started with API Calls](https://www.m3ter.com/docs/guides/m3ter-apis/getting-started-with-api-calls)
for detailed guidance on how to use our API to:

- Create a Service User and add permissions.
- Generate access keys for the Service User.
- Use basic authentication to obtain a Bearer Token.

For further guidance, also see
[Creating and Configuring Service Users](https://www.m3ter.com/docs/guides/organization-and-access-management/managing-users/creating-and-configuring-service-users).

## Other Languages

If you want to work with the m3ter REST APIs using other languages such as:

- Python
- JavaScript
- C++

Please see the
[Developer Tools](https://www.m3ter.com/docs/guides/developer-tools) topic in
our main documentation for information about available SDKs.

# Authentication

&lt;!-- ReDoc-Inject: &lt;security-definitions&gt; --&gt;</description>
  <url>https://www.m3ter.com</url>
  <licenses>
    <license>
      <name>Apache-2.0</name>
    </license>
  </licenses>
  <developers>
    <developer>
      <name>M3ter</name>
      <email>sdks@m3ter.com</email>
    </developer>
  </developers>
  <scm>
    <connection>scm:git:git://github.com/m3ter-com/m3ter-sdk-java.git</connection>
    <developerConnection>scm:git:git://github.com/m3ter-com/m3ter-sdk-java.git</developerConnection>
    <url>https://github.com/m3ter-com/m3ter-sdk-java</url>
  </scm>
  <dependencies>
    <dependency>
      <groupId>com.m3ter</groupId>
      <artifactId>sdk-java-client-okhttp</artifactId>
      <version>0.5.0</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>org.jetbrains.kotlin</groupId>
      <artifactId>kotlin-stdlib-jdk8</artifactId>
      <version>1.8.0</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>
</project>

Metadata

Age:1 month ago

Licenses:

Apache-2.0

Organization

com.m3ter

External Resources

Project URL

Source Control

Known Contributors

M3ter

OSS Index

View