API Overview

This page summarizes the core concepts of the Mednet EDC REST API and how the SDK interacts with it.

Base URL

The SDK communicates with the production API at https://edc.prod.imednetapi.com by default. Override this with IMEDNET_BASE_URL or the base_url argument to load_config for a private deployment. See Configuration for details.

Authentication

All requests must include x-api-key and x-imn-security-key headers. The BaseClient handles shared initialization while the Client and AsyncClient rely on imednet.config.load_config() to read IMEDNET_API_KEY and IMEDNET_SECURITY_KEY from the environment and populate these headers automatically. See Configuration for more information.

HTTP methods and errors

The API primarily supports GET and POST requests. Non‐successful status codes raise typed exceptions:

400 – ValidationError
401 – AuthenticationError
403 – AuthorizationError
404 – NotFoundError
429 – RateLimitError
5xx – ServerError

See Retry Policy and Error Handling for examples of handling these errors and configuring custom retry logic.

Filtering

Endpoints accept a filter parameter that matches the syntax documented in the Mednet API guide. For clinical data queries, recordDataFilter can be supplied alongside filter. See imednet.endpoints.records for usage examples.

Some endpoints (StudiesEndpoint, FormsEndpoint, IntervalsEndpoint, and VariablesEndpoint) maintain an internal cache. They accept a refresh argument to force a reload of cached data. This flag is not a general filtering option and has no effect on other endpoints.

Dates must use UTC timestamps except where noted. When filtering visits by startDate, dueDate, endDate or visitDate, use YYYY-MM-DD. String values containing spaces or special characters must be wrapped in double quotes. For example: siteName=="My Site".

Filter helper

Use imednet.utils.filters.build_filter_string() to construct filter expressions from a mapping. Values containing spaces must be wrapped in double quotes. Example:

build_filter_string({"site_name": "Bright Test Site"})
# siteName=="Bright Test Site"

Error responses

When a request fails, error details are returned in the metadata section of the response body. Validation errors include the offending field and value. Example:

{
  "metadata": {
    "status": "BAD_REQUEST",
    "path": "/api/v1/edc/studies",
    "timestamp": "2018-10-18 05:46:29",
    "error": {
      "code": "1000",
      "description": "Field raised validation errors",
      "field": {
        "attribute": "page",
        "value": "XX"
      }
    }
  }
}

Error response fields

code: Error code
description: Error description message
field.attribute: Origination request attribute which caused the error
field.value: The value of request attribute passed in the request

Error codes

1000: Validation error. Request contain invalid value.
9000: Unknown error. Please contact Mednet support for assistance.
9001: Unauthorized error. Insufficient permission to retrieve data.