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.
Optiion
|
Use for |
API key
|
In server-to-server integration scenarios, a client application requires complete access to Graviti and does not require the security permissions of the current user.
|
User login + password
|
When developing client applications that interact with Graviti on behalf of the current user, it is essential that the user trusts the application and is willing to provide their login credentials within the application.
|
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:
Replace
|
With |
YOUR_API_KEY |
API key from Authorized applications screen |
Important note: By default, the oAuth service does not provide a refresh token in this specific scenario. If you require a refresh token when utilizing an API key, you can include the parameter obtain_refresh_token=true
|
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:
Replace
|
With |
CLIENT-ID, CLIENT-SECRET |
Values from Authorized applications screen |
USER-EMAIL, USER-PASSWORD |
Credentials of user who want to access API |
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:
Replace
|
With |
CLIENT-ID, CLIENT-SECRET |
Values from Authorized applications screen |
YOUR_REFRESH_TOKEN |
The refresh token value returned by the oAuth service |
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