Graviti application programming interface overview

Understanding Gaviti api functionality

An overview of working effectively with the api for enhanced application functionality

An API, or Application Programming Interface, is a collection of functions that enable different programs to communicate and interact with each other. Graviti offers two distinct APIs - an admin API that allows you to access and modify data stored in your Graviti database, and a member API that enables you to create applications for your members. 

The retrieved data from the API can be utilized in various ways, such as backing up the data, updating another database, displaying it on a webpage, or passing it to another program for further analysis or reporting.

For example, with  Graviti's API , you can accomplish tasks like generating an Excel file that retrieves all your contacts with a single click and automatically generates a report or a chart. Additionally, you can integrate code into a desktop database like Access or FileMaker to regularly check your Graviti account for new or updated records and automatically download them.

Furthermore, you can automate the process of backing up your Graviti contact database by retrieving and storing backup copies regularly. If the customization options of Graviti's member directory widget are insufficient for your requirements, you can develop your own website plugin to display a specially formatted list of contacts.

Other possibilities include updating Graviti email preferences using an unsubscribe list managed through an external email system or creating and updating payments in Graviti using information stored in an external accounting system.

An API is composed of multiple API calls, each serving a specific function. For instance, Graviti's Membership Levels API call allows you to retrieve comprehensive details about your membership levels. When making an API call, you can include parameters, which are instructions or information used by the API to process your request.

ACCESSING GRAVITI 'S APIS

Graviti offers two options for accessing its APIs - from a third-party server or application, or directly from a  Graviti site page. To understand the distinctions between these options, refer to the API access options documentation.

Graviti's API follows the RESTful web service principles. API calls for Version 1 are made through HTML GET, PUT, POST, or DELETE requests, and they can be formatted in either JSON or XML.

AUTHENTICATION

To ensure security and prevent unauthorized access to your data, every Graviti API call must include authentication information that verifies your account. The authentication process and the method of passing this information differ based on whether you are accessing the API from a third-party server or application, or directly from a Graviti site page. For more detailed information, please refer to the API access options documentation.

VERSIONING

Including the version number of the Graviti API in the API call ensures that existing applications can continue to operate even after new versions are released. In the given scenario, the API call specifies the version 1 of the Graviti admin API by using the value "v1".

GET https://api.graviti.systems/v1/Accounts

A call to the base API – https://api.graviti.systems  – will return a list of available API versions.

API RESPONSES

You have the option to receive the results of Graviti API calls in either JSON (JavaScript Object Notation) or XML (Extensible Markup Language) formats. By default, the response format is JSON. If you want to specify a different format, include the corresponding field in the HTTP header.

Accept: application/{format}

The desired response format can be specified as either JSON or XML with the {format} placeholder. In addition, if you want to compress the response, you can include the following field in the HTTP header.

Accept-Encoding: gzip, deflate

If you need more details on compressing data in server responses, please refer to the documentation on HTTP compression.

As for the limits on API requests, the current restrictions are as follows:

• To retrieve a list of contacts, you are allowed 40 requests per minute.
• To fetch a specific contact by identifier, you can make up to 120 requests per minute.
• For other types of requests, the limit is 400 requests per minute.

API STATUS CODES

Graviti's API is designed for developers who have technical expertise. If you require assistance, we offer support through email or our developers forum.

When making an API call with Graviti's API, along with the results, you will receive a status code indicating the state of the requested operation. These status codes follow standard HTTP status codes and include the following:

• 200: The request to Graviti's server was successful, and you will receive a response.
• 304: The information you requested has been previously supplied, so it is being returned from the cache instead of the server.
• 400: Graviti's server could not understand the request. This could be due to missing required parameters, invalid data, improper syntax in your $filter or $select parameters or reaching the contact limit for the billing plan. The response body will contain the following fields:
  • Code: A brief summary of the error (e.g., Validation).
  • Message: A high-level description of the error.
  • Details: Specific information about the field name, value, and violation that caused the error.
•  401: The API key required for authenticating your account was either not provided or not valid.
• 403: Your authentication information is correct, but access to the requested resource is denied, possibly due to an invalid resource ID provided
• 404: The resource you are trying to access does not exist or is not available.
• 404.14: Your API call exceeds the server's processing capacity. The maximum query length allowed is 4096 characters.
• 429: Graviti's server has received too many requests from your account. To prevent system slowdowns, there is a limit on the number of requests per minute. It is advisable to adjust your request rate based on such responses. Otherwise, the API access may be blocked considering it as an HTTP flood.
• 500: Graviti's server has encountered an error and is unable to fulfill the request.
• 503: Graviti's server is currently unavailable due to being overloaded or undergoing maintenance.

These status codes will provide you with information on the outcome of your API requests.

API AUTHENTICATION

UNDERSTANDING AUTHENTICATION OPTIONS

Every Graviti API call requires an authentication token. This guide will walk you through the process of obtaining this token.

To obtain an authentication token, you will need to interact with Graviti's authentication service, which follows the oAuth 2.0.

The oAuth 2.0 standard provides various methods for authentication, and the choice of method depends on the type of application you intend to develop.

HOW TO OBTAIN AUTHENTICATION TOKENS

The process of acquiring authentication tokens is reliant on the chosen method of authentication.

USING THE API KEY

Choose this alternative for situations where a server-to-server integration is required, and a client application needs unrestricted access to the Graviti system without relying on the current user's security permissions. To obtain an access token using the API key, you will need to submit the following request:

POST /auth/token HTTP/1.1

Host: api.graviti.systems

Authorization: Basic BASE64_ENCODED("APIKEY:YOUR_API_KEY")

Content-type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=auto

In this template, you should replace the following:

Example:

grant_type=client_credentials&scope=auto&obtain_refresh_token=true

Your finally request will look like:

POST /auth/token HTTP/1.1

Host: api.graviti.systems

Authorization: Basic QVBJS0VZOm85c2U4N3Jnb2l5c29lcjk4MDcwOS0=

Content-type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=auto

WITH USER’S LOGIN AND PASSWORD

Select this choice when developing client applications that interact with Graviti on behalf of the user who is currently logged in. This option is suitable when the user has confidence in the application and is willing to enter their login credentials directly into it.

To acquire an access token using the user's login and password, you will need to submit the following request:

POST /auth/token HTTP/1.1

Host: api.graviti.systems

Authorization: Basic BASE64_ENCODED("CLIENT-ID:CLIENT-SECRET")

Content-type: application/x-www-form-urlencoded

grant_type=password&username=USER_EMAIL&password=USER_PASSWORD&scope=auto

In this template, you should replace the following:

So finally, your request will look like:

POST /auth/token HTTP/1.1

Host: api.graviti.systems

Authorization: Basic dGNSc25xazRtcDo5OHdlcjd0OTg3YTlzMDdkZjk3OGE=

Content-type: application/x-www-form-urlencoded

grant_type=password&[email protected]&password=pwd123&scope=auto

 HOW TO REFRESH TOKENS

To refresh the token, you have to make the following request:

POST /auth/token HTTP/1.1

Host: api.graviti.systems

Authorization: Basic BASE64_ENCODED("CLIENT-ID:CLIENT-SECRET")

Content-type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN

In this template, you should replace the following:

So finally, your request will look like:

POST /auth/token HTTP/1.1

Host: api.graviti.systems

Authorization: Basic dGNSc25xazRtcDo5OHdlcjd0OTg3YTlzMDdkZjk3OGE=

Content-type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=bGlvYXUyzZXJsaWtnamxrc2RuZi4=

WORKING WITH THE API

HOW DOES THE API KNOW WHO MAKES A CALL?

When the Graviti API receives an HTTP request, it verifies the authentication token associated with the request. If the token is invalid or missing, the API will respond with an error message in the form of HTTP 401 Unauthorized.

HOW TO PASS AUTH TOKEN TO PUBLIC API?

The authentication token should be included in the Authorization header of the API request, using the Bearer scheme.

Example:

GET /v2.1/accounts HTTP/1.1

Host: api.graviti.systems  

User-Agent: MySampleApplication/0.1

Accept: application/json

Authorization: Bearer YOUR_TOKEN_HERE

Related topics

• Graviti Api Calls Made Through Html Get Put Post Or Delete Requests