Getting Started

This page provides entry points for the most common IRI Facility API audiences.

Normative requirements are defined in the iri-facility-api-docs repository. This site explains how the pieces fit together.

Before you begin

Become familiar with three concepts:

  1. An IRI Resource represents a facility resource that can be described and discovered.
  2. resource_type identifies what kind of resource is being represented.
  3. Typed links can advertise relationships, related state, and operation entry points.

Read Core Concepts for the terminology and Hypermedia and Discovery for the traversal model.

I am implementing IRI at a facility

Recommended path:

  1. Review IRI Architecture.
  2. Review the IRI 2.0 specification.
  3. Review the v2 OpenAPI definition.
  4. Identify the IRI Resource Types your facility will expose using the Resource Type registry.
  5. Review applicable Resource Definition Profiles.
  6. Review the Link Relation Registry.
  7. Implement and validate the API using the guidance in Implementation Guide.

A facility implementation should use the registered semantics rather than creating local meanings for shared IRI identifiers.

I am building an IRI client

A client should be designed around representations and advertised links rather than hard-coded facility URL layouts.

Recommended path:

  1. Retrieve a known or discovered IRI resource representation.
  2. Inspect resource_type.
  3. Interpret the common resource representation.
  4. Apply the Resource Definition Profile associated with that type when needed.
  5. Inspect _links for available relationships and operation entry points.
  6. Follow the advertised URI rather than constructing a URI from assumed path templates.
  7. Use an advertised service description, when provided, to obtain the applicable machine-readable API contract.

See Hypermedia and Discovery.

I am building a workflow orchestrator, MCP server, or AI agent

Treat IRI representations as the authoritative source of navigational information available at runtime.

The preferred pattern is:

Discover resource
      │
      ▼
Inspect representation
      │
      ├── resource_type ──► semantic interpretation
      │
      └── _links ─────────► available traversal / operations
                                │
                                ▼
                         follow advertised URI

An agent should not guess a path such as /jobs/{resource_id} simply because another facility uses that structure. If the operation is discoverable through a registered relation, use the advertised target.

I am reviewing or proposing specification changes

Start with the RFC Process.

Use the repository’s issue and pull-request workflow for normative changes. This site should document adopted concepts but should not become a second standards-development channel.

Suggested reading order

  1. IRI Architecture
  2. Core Concepts
  3. IRI 2.0
  4. Hypermedia and Discovery
  5. IRI Registry
  6. Implementation Guide
  7. Examples