Create vs Update

The Revision API handles creating and updating resources based on how you identify them in your requests.

Create vs Update

Create: Send a request without an id or ref field to create a new resource.

Update: Include an id or ref field to update an existing resource.

Using IDs

IDs are system-generated identifiers that Revision assigns when resources are created.

Update with ID:

{
  "id": "8hgFyqbE9a6",
  "name": "Updated Component Name",
  "typeId": "eE1d4atd1Og"
}

This will update the existing component with ID 8hgFyqbE9a6.

Using Refs

Refs are user-defined identifiers that you can assign to components and diagrams. They work like custom IDs that you control.

Create with Ref:

{
  "ref": "my-api-gateway",
  "name": "API Gateway",
  "typeId": "eE1d4atd1Og"
}

If no component exists with ref: "my-api-gateway", this creates a new component.

Update with Ref:

{
  "ref": "my-api-gateway",
  "name": "Updated API Gateway",
  "typeId": "kebvFua3Uxt"
}

If a component already exists with ref: "my-api-gateway", this updates it.

ID vs Ref

Field	Generated by	Used for	Behavior
id	System	All resources	Must match existing ID or fails
ref	User	Components & Diagrams only	Creates new if doesn't exist

When to Use Refs

Refs are useful when:

• Predictable identifiers: You want meaningful names instead of random IDs
• CI/CD pipelines: Consistent identifiers across deployments
• Cross-references: Referencing resources before they exist in the same request

Example with cross-references:

{
  "components": [
    {
      "ref": "frontend-app",
      "name": "Frontend Application"
    }
  ],
  "diagrams": [
    {
      "ref": "app-diagram",
      "componentInstances": [
        {
          "component": "frontend-app"  // References the ref above
        }
      ]
    }
  ]
}

Important difference:

• IDs must match: If you send an id, it must match an existing resource or the request fails
• Refs create if missing: If you send a ref that doesn't exist, it creates a new resource with that ref

Partial Updates

When updating resources, you only need to send the fields you want to change:

• Omitted fields - Remain unchanged
• Set to null - Explicitly clears the field value
• Include field - Updates to the new value

Example - Update only name:

{
  "id": "8hgFyqbE9a6",
  "name": "New Name"
  // desc, state, etc. remain unchanged
}

Example - Clear description:

{
  "id": "8hgFyqbE9a6", 
  "desc": null  // Removes the description
}