REST API

REST API#

Introduction#

Rave provides two distinct APIs to support both end-user functionality and application management:

  1. Client API: Powers the Rave SDKs and serves as the API for end-user interactions such as authentication, identity management, leaderboards, and achievements.

  2. Portal API: Powers the Rave Developer Portal and serves as the API for configuring applications, managing users, and administering backend settings.

Together, these APIs provide full support for both application integrations and administrative operations.

When to Use Each API#

Client API (End-User API)#

The Client API powers Rave’s SDKs and exposes endpoints for integrating end-user functionality. It is designed for end-user interactions and can now serve custom integrations beyond the SDK context.

Key features include:

  • Authentication and Identity Management: Handle user authentication, sessions, and profiles.

  • Leaderboards: Manage user rankings for competitions and activities.

  • Achievements: Track user achievements.

  • Gifts: Manage Gifts and Requests.

  • Activities and Contacts: Facilitate social interactions, activity tracking, and user engagement.

Use the Client API for:

  • Custom Server-Side Integrations: Server-to-server communication to extend SDK capabilities.

  • Web Applications: Integrate features such as leaderboards or achievements into your website.

  • New Platforms: Support for platforms where no SDK currently exists.

Portal API (Management API)#

The Portal API powers the Rave Developer Portal and exposes endpoints for administrators and application owners. It provides functionality to manage your application environment.

Key features include:

  • Application Configuration: Set up properties like leaderboards, achievements, and authentication rules.

  • User Management: Manage users, roles, and access permissions.

Use the Portal API for:

  • Administrative Operations: Configure application settings and manage users.

  • Backend Integration: Automate management workflows using server-to-server communication.

Authentication#

Both the Client API and Portal API require authentication to access most of their endpoints. Below are the specific mechanisms used for each API.

Portal API Authentication#

To access the Portal API, you must authenticate your requests using the Auth-token HTTP header. This header requires an Auth Token, which can be generated through the developer portal. For more info on creating these tokens please see API Tokens.

All requests must include:

  • The Auth-token header with a valid token.

  • A Content-Type header set to application/json.

Example request:

curl \
  -H "Content-Type: application/json" \
  -H "Auth-token: <API TOKEN>" \
  -X <METHOD> \
  <OTHER OPTIONS> \
  https://manage.ravesocial.co/...

For details on creating Auth Tokens, please see the API Tokens documentation.

Client API Authentication#

The Client API supports two authentication methods:

  1. SID (Session ID): The primary authentication mechanism for SDK integrations. Sessions are user-scoped, and SIDs are required for most endpoints.

  2. UserToken: Used for server-to-server communication. While the SDKs exclusively use SIDs, some endpoints (known as Multi Auth Resources) support both SIDs and UserTokens.

To generate a SID, you need to authenticate into a user account. Sessions are created per user, and the resulting SID is used as the authentication token for subsequent requests.

Example request with an SID:

curl \
  -H "Content-Type: application/json" \
  -H "SID: <SESSION ID>" \
  -X <METHOD> \
  <OTHER OPTIONS> \
  https://api.ravesocial.co/...

Example request with a UserToken:

curl \
  -H "Content-Type: application/json" \
  -H "User-Token: <USER TOKEN>" \
  -X <METHOD> \
  <OTHER OPTIONS> \
  https://api.ravesocial.co/...

Notes:

  • SIDs are typically generated through the session endpoints when a user logs in.

  • UserTokens are primarily for backend integrations and are not used by the SDKs.

Content-Type Requirement#

Both the Client API and Portal API require all requests to have the Content-Type header set to application/json.

Base URLs#

Your account manager will provide you with the appropriate base URLs for your API environment.

Error Responses#

The APIs return errors in a structured JSON format to facilitate debugging. An example is shown below:

{
    "error": {
        "message": "Invalid bearer token.",
        "code": 209
    }
}

Error Response Fields#

  • message: A human-readable description of the error.

  • code: A numeric identifier for the error type.

  • argument (optional): Indicates the specific field or parameter that caused the error, if applicable.

Example with the argument field:

{
    "error": {
        "message": "Invalid email address.",
        "code": 700,
        "argument": "email"
    }
}

Best Practices#

  • Use secure server-to-server communication for all API calls.

  • Opt for SDK usage wherever possible to simplify integrations.

  • Contact your account manager for guidance on API use.

Contents