API Reference

This documentation provides details about the OpenImpactLab API, allowing you to integrate with our platform and access its functionality programmatically.

Getting Started with the API

Our API uses REST principles and returns responses in JSON format. Base URL for all API endpoints is:

https://api.openimpactlab.org/v1

All API requests must include authentication headers and use HTTPS.

Authentication

The API uses OAuth 2.0 for authentication. To access the API, you need to:

1. Register your application in the OpenImpactLab developer portal
2. Obtain your API key and secret
3. Use these credentials to request an access token
4. Include the access token in the Authorization header of each request

Example authentication request:

POST /oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "grant_type": "client_credentials"
}

Resources

API Endpoints

Explore our specialized API endpoints with detailed documentation:

Projects

Endpoints for managing projects:

• GET /projects - List all projects
• GET /projects/{projectId} - Get a specific project
• POST /projects - Create a new project
• PUT /projects/{projectId} - Update a project
• DELETE /projects/{projectId} - Delete a project

Users

Endpoints for user management:

• GET /users - List all users
• GET /users/{userId} - Get a specific user
• POST /users - Create a new user
• PUT /users/{userId} - Update a user

Organizations

Endpoints for organization management:

• GET /organizations - List all organizations
• GET /organizations/{orgId} - Get a specific organization
• POST /organizations - Create a new organization
• PUT /organizations/{orgId} - Update an organization

Request and Response Format

All API requests should include the following headers:

Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Response codes follow standard HTTP status codes:

• 200 OK - The request was successful
• 201 Created - A new resource was successfully created
• 400 Bad Request - The request was invalid
• 401 Unauthorized - Authentication failed
• 403 Forbidden - You don't have permission to access the resource
• 404 Not Found - The resource was not found
• 500 Internal Server Error - Something went wrong on the server

Rate Limiting

To ensure service stability, API requests are rate limited to 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.

The response headers include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1619203200

Webhooks

OpenImpactLab also provides webhooks for real-time notifications about events on the platform:

• Project created or updated
• New application submitted
• Status changes
• Messages and comments

To set up a webhook, register your endpoint URL in the developer portal.

SDK and Libraries

We provide official client libraries to simplify API integration:

• JavaScript: npm install openimpactlab-js
• Python: pip install openimpactlab-python
• Ruby: gem install openimpactlab-ruby

These libraries handle authentication, request formatting, and response parsing for you.