Quick Start Guide

Get familiar with RegistryAccord specifications and understand how to work with the protocol.

Current Status

RegistryAccord is in the specification phase. This guide shows you how to explore the specs, understand the architecture, and prepare for future implementation.

What You Can Do Now

1. Explore the Specifications

All API specifications are complete and published:

7 core services with 114 endpoints
Complete OpenAPI 3.1 specifications
50+ JSON Schema data models
34 workflow examples

Access the specs:

Clone the specs repository

git clone https://github.com/RegistryAccord/registryaccord-specs.git
cd registryaccord-specs

Browse the structure

ls -la openapi/ # OpenAPI specifications
ls -la schemas/ # JSON schemas
ls -la examples/ # Workflow examples

2. Understand the Services

Identity Service (22 endpoints)

WebAuthn/Passkey authentication
OAuth2/OIDC authorization
Consent management
Organization management

Content Registry (20 endpoints)

Content creation and versioning
JSON-LD metadata
License management
Collection organization

Payments & Payouts (26 endpoints)

Payment processing
Revenue splits
Subscription billing
Dispute handling

Storage Gateway (12 endpoints)

File upload/download
Content addressing
Multi-provider support
Encryption

Feed Generator (7 endpoints)

Feed generation
Ranking algorithms
Fairness audits
Dispute resolution

Revenue Services (16 endpoints)

Ad campaigns
RTB integration
Brand safety
Performance reporting

Analytics (11 endpoints)

Event tracking
Metrics querying
Privacy budgets
Data exports

3. View Example Workflows

Each service includes complete workflow examples:

View identity examples

cat examples/identity/01-register-user.yaml
cat examples/identity/02-authenticate-webauthn.yaml

View content examples

cat examples/content/01-create-article.yaml
cat examples/content/02-version-content.yaml

View payment examples

cat examples/payments/01-create-payment-intent.yaml
cat examples/payments/02-setup-revenue-split.yaml

Example workflow structure:

name: User Registration with WebAuthn
description: Complete user registration flow

steps:
  - name: Create identity
    request:
      method: POST
      path: /v1/identities
      headers:
        Content-Type: application/json
      body:
        display_name: "Jane Doe"
        email: "jane@example.com"
    
    response:
      status: 201
      headers:
        Location: /v1/identities/did:key:z6Mk...
      body:
        id: "did:key:z6Mk..."
        display_name: "Jane Doe"
        email: "jane@example.com"
        created_at: "2024-01-15T10:30:00Z"

Working with OpenAPI Specifications

View Specifications Locally

Option 1: Use Swagger UI

# Install Swagger UI
npm install -g swagger-ui

# Serve the Identity spec
swagger-ui openapi/identity/v1/openapi.yaml

# Opens at http://localhost:3000

Option 2: Use Redoc

# Install Redoc CLI
npm install -g redoc-cli

# Serve the Identity spec
redoc-cli serve openapi/identity/v1/openapi.yaml

# Opens at http://localhost:8080

Option 3: Use Online Viewers

Upload any OpenAPI spec to:

Swagger Editor: https://editor.swagger.io/
Redocly: https://redocly.github.io/redoc/

Generate Mock Servers

Test API contracts without building the full service:

# Install Prism
npm install -g @stoplight/prism-cli

# Start mock server for Identity service
prism mock openapi/identity/v1/openapi.yaml

# Mock server runs at http://localhost:4010

Test the mock:

# Create a mock identity
curl -X POST http://localhost:4010/v1/identities \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Test User",
  "email": "test@example.com"
}'

Understanding API Patterns

1. Authentication

All RegistryAccord services use OAuth2 with fine-grained scopes:

POST /v1/identities HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

Body:

{
  "display_name": "Jane Doe",
  "email": "jane@example.com"
}

Common scopes:

identity:read - Read identity information
identity:write - Create/update identities
content:read - Read content
content:write - Create/update content
payments:read - Read payment information
payments:write - Process payments

2. Standard Request Format

POST /v1/RESOURCE_ID HTTP/1.1
Host: api.registryaccord.com
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Idempotency-Key: UUID_VALUE

Body:

{
  "field1": "value1",
  "field2": "value2"
}

3. Standard Response Format

Success (2xx):

HTTP/1.1 201 Created
Location: /v1/RESOURCE_ID/ID_VALUE
Content-Type: application/json

{
  "id": "resource_id",
  "field1": "value1",
  "created_at": "2024-01-15T10:30:00Z"
}

Error (4xx/5xx):

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://api.registryaccord.com/errors/validation-error",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The 'email' field must be a valid email address",
  "instance": "/v1/identities"
}

4. Pagination

List endpoints support cursor-based pagination:

GET /v1/identities?limit=20&cursor=abc123 HTTP/1.1
Authorization: Bearer JWT_TOKEN

Response:

{
  "items": [...],
  "pagination": {
    "next_cursor": "xyz789",
    "has_more": true,
    "total_count": 150
  }
}

Key Concepts

Decentralized Identifiers (DIDs)

All identities use W3C DIDs:

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

Format:

did - DID URI scheme
key - DID method (public key)
z6Mk... - Method-specific identifier

Content Addressing

Files use SHA-256 content addressing:

sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Versioning

All APIs use date-based versioning:

/v1/identities → Version 1 (2025-01-15)

Header-based version negotiation:

API-Version: 2025-01-15

Next Steps

For Implementers

Phase 1: Learn the Specs

Read through the OpenAPI specifications
Understand the data models
Study the authentication flows
Review example workflows

Phase 2: Design Your Implementation

Choose your tech stack
Plan your database schema
Design your deployment architecture
Map RA specs to your implementation

Phase 3: Build & Test

Implement core services
Use conformance tests (coming soon)
Validate against specs
Earn certification

For App Developers

Current Actions:

Study the API contracts
Understand available endpoints
Review data models and schemas
Plan your integration approach

Wait For:

SDK releases (TypeScript, Python, Go, etc.)
Reference implementations
Live API endpoints
Developer sandboxes

For Contributors

How to Contribute:

Join GitHub Discussions
Review and comment on specs
Suggest improvements
Submit example workflows
Help write documentation

Common Patterns

Creating Resources

POST /v1/RESOURCE_ID
Authorization: Bearer JWT_TOKEN
Content-Type: application/json
Idempotency-Key: UUID_VALUE

Body:

RESOURCE_DATA

Response: 201 Created

Location: /v1/RESOURCE_ID/ID_VALUE

Body:

CREATED_RESOURCE_DATA

Reading Resources

GET /v1/RESOURCE_ID/ID_VALUE
Authorization: Bearer JWT_TOKEN

Response: 200 OK

Body:
```json
RESOURCE_DATA

Updating Resources

PATCH /v1/RESOURCE_ID/ID_VALUE
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Body:

PARTIAL_UPDATE_DATA

Response: 200 OK

Body:
```json
UPDATED_RESOURCE_DATA

Deleting Resources

DELETE /v1/RESOURCE_ID/ID_VALUE
Authorization: Bearer JWT_TOKEN

Response: 204 No Content

### Listing Resources

```http
GET /v1/RESOURCE_ID?limit=20&cursor=CURSOR_VALUE
Authorization: Bearer JWT_TOKEN

Response: 200 OK

Body:
```json
{
  "items": [RESOURCE1, RESOURCE2, ...],
  "pagination": {
    "next_cursor": NEXT_CURSOR,
    "has_more": HAS_MORE
  }
}

Standards Compliance

RegistryAccord follows these standards:

OpenAPI 3.1.0 - API specification format
JSON Schema Draft 2020-12 - Data validation
RFC 7807 - Problem Details for HTTP APIs
RFC 8594 - Deprecation Header
OAuth 2.0 & OIDC - Authentication/authorization
WebAuthn - Phishing-resistant authentication
W3C DIDs - Decentralized identifiers
JSON-LD - Semantic metadata
W3C Trace Context - Distributed tracing

Resources

Specifications:

GitHub Repository: https://github.com/RegistryAccord/registryaccord-specs
OpenAPI Specs: openapi/ directory
JSON Schemas: schemas/ directory
Examples: examples/ directory

Community:

GitHub Discussions: https://github.com/RegistryAccord/registryaccord-specs/discussions
GitHub Issues: https://github.com/RegistryAccord/registryaccord-specs/issues

Tools:

Swagger UI: https://swagger.io/tools/swagger-ui/
Redoc: https://redocly.com/redoc/
Prism Mock Server: https://stoplight.io/open-source/prism

Questions?

Join the community discussion on GitHub to ask questions, share feedback, and collaborate on the protocol specifications.

What You Can Do Now​

1. Explore the Specifications​

2. Understand the Services​

3. View Example Workflows​

Working with OpenAPI Specifications​

View Specifications Locally​

Generate Mock Servers​

Understanding API Patterns​

1. Authentication​

2. Standard Request Format​

3. Standard Response Format​

4. Pagination​

Key Concepts​

Decentralized Identifiers (DIDs)​

Content Addressing​

Versioning​

Next Steps​

For Implementers​

For App Developers​

For Contributors​

Common Patterns​

Creating Resources​

Reading Resources​

Updating Resources​

Deleting Resources​

Standards Compliance​

Resources​

Questions?​

What You Can Do Now

1. Explore the Specifications

2. Understand the Services

3. View Example Workflows

Working with OpenAPI Specifications

View Specifications Locally

Generate Mock Servers

Understanding API Patterns

1. Authentication

2. Standard Request Format

3. Standard Response Format

4. Pagination

Key Concepts

Decentralized Identifiers (DIDs)

Content Addressing

Versioning

Next Steps

For Implementers

For App Developers

For Contributors

Common Patterns

Creating Resources

Reading Resources

Updating Resources

Deleting Resources

Standards Compliance

Resources

Questions?