WiseMapping Open Source

The backend documentation is organized into several key areas:

• rest-api/: Contains legacy REST services documentation.
• telemetry/: Contains documentation for OpenTelemetry and metrics implementation.
• openapi-specs/: Contains the source-of-truth API specifications:
  • openapi.yaml: The main OpenAPI 3.0 specification.
  • mindmap-endpoints.yaml: Specific endpoints related to mindmap operations.
  • collaboration-admin-endpoints.yaml: Endpoints for administration and collaboration features.

The WiseMapping documentation is organized into three primary categories based on your role:

For Developers

• API Documentation: Detailed REST API reference, including authentication, endpoints, data models, and error handling.
• Backend Documentation: Specifics regarding backend implementation and development guidelines.
• OpenAPI Specifications: Machine-readable API definitions in OpenAPI format.

For System Administrators

• Database Configuration: Setup instructions and migration scripts.
• Deployment Guide: Documentation for Docker and general deployment.
• Telemetry & Metrics: Information on monitoring and observability.

For Integration

• REST Services: Documentation for legacy REST services, including CURL examples.
• API Examples: Workflow examples for integrating with the system.

The API uses standard HTTP status codes. Errors are returned in a JSON format containing a message, a specific error code, and optional field-level details.

Common Status Codes:

• 200 OK / 201 Created / 204 No Content: Success
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required or invalid
• 403 Forbidden: Access denied (e.g., admin required)
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

{
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional error details"
  }
}

All backend documentation must adhere to the following standards:

• Use Markdown format.
• Include code examples (e.g., CURL or JSON) where applicable.
• Maintain up-to-date OpenAPI specifications.
• Document all new endpoints and changes.
• Explicitly include authentication requirements.
• Provide error handling examples.

The AuthenticationProviderLDAP handles the authentication lifecycle. When a user logs in:

1. The system checks if the user exists via other authentication types.
2. An LDAP bind attempt is made using the provided credentials.
3. Upon success, attributes (email, first name, last name) are extracted from the LDAP server.
4. The user is synchronized with the WiseMapping database (created if new, updated if existing).
5. A JWT is returned using the email address retrieved from LDAP (which may differ from the username used to log in).

Note: If the LDAP server is unavailable, the system falls back to standard DATABASE authentication.

Choose the configuration that best fits your deployment architecture:

The MariaDB deployment is optimized with the following technical specifications:

• Driver & Dialect: Uses org.mariadb.jdbc.Driver and org.hibernate.dialect.MariaDBDialect (native MariaDB, not MySQL compatibility mode).
• Character Set: Configured with utf8mb4 character set and utf8mb4_unicode_ci collation for full UTF-8 support.
• Case Sensitivity: Uses --lower_case_table_names=1 to ensure consistent lowercase naming conventions across Linux, Mac, and Windows.
• Data Storage: Uses MEDIUMBLOB for XML mindmap data and MEDIUMTEXT for descriptions to support large mindmaps.

To prevent abuse, the API implements rate limiting. You can monitor your usage via the following response headers:

• X-RateLimit-Limit: Maximum requests allowed in the current window.
• X-RateLimit-Remaining: Number of requests remaining in the current window.
• X-RateLimit-Reset: The timestamp when the rate limit window resets.

If you exceed the limit, the API will return a 429 Too Many Requests status code.

Deploy WiseMapping with a MariaDB 11.4 database using Docker Compose. This configuration uses the native MariaDB JDBC driver and dialect.

Steps

1. Create a .env file from .env.example and populate it with the required environment variables.
2. Run the deployment command:

   docker-compose up -d

3. Access the application at http://localhost or http://localhost:${WISEMAPPING_PORT}.

Default Credentials

• Test User: test@wisemapping.org / test
• Admin User: admin@wisemapping.org / testAdmin123