RefPack Registry API Reference

Programmatically interact with the RefPack Registry to search, download, and manage dataset packages. Authentication is required via an X-API-Key header for push and archive operations.

Package Management

GET /packages Search/List Packages

Retrieves a list of packages, optionally filtered by a search query and archive status. Supports pagination.

Parameters

Search term to filter packages by ID, name, or description.

Set to true to include archived packages in the results.

Page number for pagination (minimum 1).

Number of items per page (1-100).

Example Request URL

https://stor.refwire.online/packages?q=countries&page=1&pageSize=10

Example Response (200 OK)


{
  "items": [
    {
      "id": "vendor/country-codes",
      "name": "Country Codes ISO3166",
      "description": "List of country codes based on ISO3166.",
      "version": "1.2.0",
      "isArchived": false,
      "updatedAt": "2024-05-20T10:00:00Z"
    }
  ],
  "totalCount": 1,
  "pageNumber": 1,
  "pageSize": 10,
  "totalPages": 1
}
GET /packages/advanced-search Advanced Search Packages

Perform an advanced search for packages with filtering by tags, owner, and additional custom filters, with pagination.

Parameters

Search term to filter packages.

Array of tags to filter by.

Filter by package owner ID.

Include archived packages in results.

Additional custom filters in format "key1:value1,key2:value2".

Example Request URL

https://stor.refwire.online/packages/advanced-search?q=countries&tags=geography&ownerId=vendor
POST /packages Upload/Push Package 🔐

Uploads a new RefPack .zip file to the registry. Requires X-API-Key authentication.

Headers

API key for authentication.

Request Body

Content-Type: multipart/form-data

The RefPack .zip file to upload (must end with .zip or .refpack.zip).

The owner ID for the package.

Example Response (200 OK)


{
  "success": true
}

Example Response (400 Bad Request - Validation Error)


{
  "error": "Package validation failed",
  "message": "The package does not conform to RefPack specification or validation failed"
}
GET /packages/{id} Download Package ZIP

Downloads the full RefPack .zip file for a specific package ID and optionally a version.

Path Parameters

The unique identifier of the package.

Query Parameters

Specific version of the package (must be valid SemVer).

Example Response (200 OK)

Content-Type: application/zip

Content-Disposition: attachment; filename="vendor-country-codes-1.0.0.refpack.zip"

The response body will be the binary content of the .refpack.zip file.

GET /packages/{id}/meta Get Package Metadata

Retrieves the manifest metadata for a specific package ID and optionally a version. If version is omitted, latest is assumed.

Path Parameters

The unique identifier of the package (e.g., vendor/country-codes).

Query Parameters

Specific version of the package (must be valid SemVer).

Example Response (200 OK)


{
  "id": "vendor/country-codes",
  "version": "1.2.0",
  "title": "Country Codes ISO3166",
  "idField": "code",
  "nameField": "name",
  "description": "Comprehensive list of country codes based on the ISO3166 standard.",
  "authors": ["Vendor Name", "Community Contributor"],
  "createdUtc": "2024-05-20T09:00:00Z",
  "tags": ["countries", "iso3166", "geography"],
  "license": "MIT"
}
GET /packages/{id}/data Get Package Data

Retrieves the data.json content for a specific package.

Path Parameters

Query Parameters

Example Response (200 OK)

Content-Type: application/json

Returns the raw JSON data from the package's data.json file.

GET /packages/{id}/schema Get Package Schema

Retrieves the data.schema.json content for a specific package.

Path Parameters

Query Parameters

Example Response (200 OK)

Content-Type: application/json

Returns the JSON schema from the package's data.schema.json file.

GET /packages/{id}/changelog Get Package Changelog

Retrieves the data.changelog.json content for a specific package.

Path Parameters

Query Parameters

Example Response (200 OK)

Content-Type: application/json

Returns the changelog JSON from the package's data.changelog.json file.

GET /packages/{id}/readme Get Package Readme

Retrieves the data.readme.md content for a specific package.

Path Parameters

Query Parameters

Example Response (200 OK)

Content-Type: text/markdown

Returns the markdown content from the package's data.readme.md file.

GET /packages/{id}/versions Get Package Versions

Lists all versions of a specific package.

Path Parameters

Example Response (200 OK)


{
  "packageId": "vendor/country-codes",
  "versions": [
    {
      "version": "1.2.0",
      "createdAt": "2024-05-20T10:00:00Z",
      "isArchived": false
    },
    {
      "version": "1.1.0",
      "createdAt": "2024-04-15T08:30:00Z",
      "isArchived": false
    }
  ]
}
POST /packages/{id}/archive Archive Package 🔐

Mark a package or specific version as archived. Requires X-API-Key authentication.

Headers

API key for authentication.

Path Parameters

Query Parameters

Specific version to archive. If omitted, all versions are archived.

Example Response (200 OK)


{
  "success": true,
  "packageId": "vendor/country-codes",
  "version": "1.0.0",
  "message": "Package 'vendor/country-codes' version '1.0.0' has been archived"
}

Common Error Responses

400 Bad Request: Invalid input, such as missing required parameters, invalid version format, or malformed package.


{
  "error": "Invalid version format",
  "message": "Version must be a valid SemVer string"
}

401 Unauthorized: Missing or invalid X-API-Key for protected endpoints.


{
  "error": "Unauthorized",
  "message": "API key is missing or invalid."
}

404 Not Found: The requested package or resource does not exist.


{
  "error": "Package not found",
  "message": "Package 'unknown/package' version 'latest' was not found"
}

409 Conflict: Package already exists or validation conflict.

500 Internal Server Error: An unexpected error occurred on the server.


{
  "title": "Internal Server Error",
  "detail": "An error occurred while processing the package",
  "status": 500
}