REST API

Both Gravity Web and Gravity Native communicate with Gravity Server using a REST API.
The api files are located in /api
The structure of these files is simple; there are a list of endpoints that connect directly to the relevant controller method. 
api.post('/api/account', use(accountController.create));
Each controller call is wrapped in a HOC (higher order component) called use. This is a middleware function that catches any errors in the controller methods, and then passes these to a global error handler – this prevents you from having to use try...catch in your application.
Protected Routes 
You can protect any API route and make it accessible to only a specific user level or API key scope using the auth.verify middleware method. You simply pass the user permission as the first permission, and an optional API scope as the second.
api.get('/api/user', auth.verify('user', 'account.read'), use(userController.get));
Learn more about API scopes and find out more about how authentication works in the next section. 
Accessing The API
You can access the API using one of two methods:
1.Using a Bearer token issued during the authentication flow
2.Using an API key 
Using Bearer Tokens
Bearer tokens are JWTs that are used to authenticate the user. You can use a Bearer token with the API by passing it in the Authorization header.
Bearer your_jwt
Using API Keys
API keys can be created by either an owner or developer permission and can be used to access any endpoint that has an API scope (see Protected Routes above). 
API keys are stored in the database in plain text to remove the decryption overhead on each API call, and so the user can retrieve an API key if they lose it. For most applications this is acceptable; if your database is breached and the API keys are stolen, an attacker already has access to all of your data, so encryption provides minimal protection in this scenario. If you want the added security, encrypt the keys before storing them. 
Basic your_api_key
The following example demonstrates how to make an API request in Javascript with the Axios package.
const res = await axios({
​
  url: 'https://yourdomain.com/api/user'
  method: 'POST',
  data: {
    email: 'kyle',
    password: 'test1'
  },
  headers: {
    Authorization: 'Basic YOUR_API_KEY'
  },
});
Rate Limiting
API requests are globally rate limited as defined by the throttle settings in config. The following end points have their own rate limits for security purposes:
All API endpoints are rate limited by the configuration settings in config/default.json -> throttle. Specific endpoints like signup and sign-in have their own throttle settings for security. 
POST /api/account
POST /api/user
POST /api/user/auth
POST /api/user/password/reset/request
POST /api/user/password/reset
API Logs
Every API request is logged in the log table by default. You can toggle this on or off using the ENABLE_API_LOGS environment variable.
ENABLE_API_LOGS=true
Swagger File
There is a swagger file included in the boilerplate with documentation and examples for each endpoint using the OpenAPI 3.0 spec. You can import this into Postman for easy testing.
Last modified 1d ago