Skip to main content
Version: 1.0.0
Last Updated: 03-12-2025
API Base URL: https://api.absch.info
IAM Authentication URL: {IAM_HOST}/realms/absch

​
Table of Contents

  1. Introduction
  2. Authentication
  3. Error Handling
  4. Rate Limiting
  5. File Upload Guidelines
  6. Security Best Practices
  7. API Endpoints
  8. Support
  9. Changelog

​
Introduction

This documentation provides detailed information about the authentication process and API endpoints. The API uses REST architecture and returns responses in JSON format.
Note: ABS refers to Access & Benefit Sharing Clearing House, which is the system that manages and tracks access to genetic resources and the sharing of benefits from their use.

​
API Versioning

The current API version is v1.0.0. The version is included in the API URL: 
https://api.example.com/v1/

​
Content Types

The API supports multiple content types depending on the endpoint:
  1. JSON Data (Default)
Content-Type: application/json
Accept: application/json
Used for most API endpoints that send and receive JSON data.
  1. Form URL Encoded
Content-Type: application/x-www-form-urlencoded
Used specifically for authentication endpoints.
  1. Multipart Form Data
Content-Type: multipart/form-data
Used for file upload endpoints (e.g., Upload Permit endpoint). Each endpoint’s documentation specifies the required Content-Type header.

​
Error Handling

The API uses standard HTTP response codes and returns consistent error objects.

​
HTTP Status Codes

Status CodeDescription
200Success
400Bad Request - See Common Error Responses
401Unauthorized - See Common Error Responses
403Forbidden - See Common Error Responses
404Not Found - See Common Error Responses
500Internal Server Error

​
Common Error Responses

All API endpoints may return the following error responses:

​
400 Bad Request

{
  "type": "https://httpstatuses.com/400",
  "title": "Invalid command error",
  "status": 400,
  "detail": ["Detailed error message"],
  "instance": null,
  "extensions": {
    "traceId": "00-798154166236981871ba3ac65fae0cfa-cc74cee507ffb0c7-00"
  }
}

​
401 Unauthorized

{
  "type": "https://httpstatuses.com/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing authentication token",
  "instance": null,
  "extensions": {
    "traceId": "00-798154166236981871ba3ac65fae0cfa-cc74cee507ffb0c7-00"
  }
}

​
403 Forbidden

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions to perform the requested action",
  "instance": null,
  "extensions": {
    "traceId": "00-798154166236981871ba3ac65fae0cfa-cc74cee507ffb0c7-00"
  }
}

​
404 Not Found

{
  "type": "https://httpstatuses.com/404",
  "title": "Resource not found error",
  "status": 404,
  "detail": "The requested resource was not found",
  "instance": null,
  "extensions": {
    "traceId": "00-231f31bee3eafc77fedba4beba6ee644-181275d8a1dabb78-00"
  }
}

​
409 Conflict

{
  "type": "https://httpstatuses.com/409",
  "title": "Business rule validation error",
  "status": 409,
  "detail": "Business rule validation failed]",
  "instance": null,
  "extensions": {
    "traceId": "00-0a4fb65c30cf063da26cdf58c0b907c2-87a2fc3d84f955d1-00"
  }
}

​
File Upload Guidelines

When uploading files through the API (e.g., permit documents), please follow these guidelines:

​
Supported File Formats

  • PDF documents (*.pdf)
  • Image files (*.jpg, *.jpeg, *.png)
  • Maximum file size: 10MB

​
File Upload Best Practices

  1. File Names
    • Use only alphanumeric characters, hyphens, and underscores
    • Avoid spaces and special characters
    • Maximum filename length: 255 characters
  2. File Content
    • Ensure files are not password protected
    • Files must be readable and not corrupted
    • Content must be clearly legible
  3. Security
    • Scan files for viruses before uploading
    • Do not upload executable files
    • Ensure files don’t contain sensitive metadata

​
Error Handling for File Uploads

  • If a file exceeds size limits, a 413 Payload Too Large response will be returned
  • Invalid file formats will result in a 400 Bad Request
  • Corrupted files will be rejected with appropriate error messages

​
Security Best Practices

  1. SSL/TLS: Always use HTTPS for API communications
  2. Token Storage:
    • Store tokens securely
    • Never expose in client-side code
    • Never log tokens or credentials
  3. Token Management:
    • Cache tokens until expiration
    • Implement automatic token refresh
    • Handle token expiration gracefully
  4. Error Handling:
    • Implement proper error handling
    • Log authentication failures
    • Monitor for suspicious activity

​
Support

For API support or questions, contact:

​
Changelog

​
Version 1.0.0 (2025-03-12)

​
Authentication & Security

  • Implemented OAuth 2.0 authentication with JWT tokens
  • Added comprehensive security best practices
  • Implemented rate limiting (100 requests per minute)

​
Documentation

  • Initial comprehensive API documentation
  • Added detailed error handling documentation
  • Added file upload guidelines and best practices

​
Developer Experience

  • Added clear examples for all endpoints
  • Included comprehensive request/response examples
  • Added detailed parameter descriptions
  • Implemented consistent error response format