There are several saved object metadata properties that we return in the API response. We should decide if/how we want to expose these properties. Because these properties are automatically updated by the saved objects client we only expose these in the response. These properties can not be created or modified by API consumers in requests.

• updatedAt
• createdAt
• updatedBy
• createdBy
• managed

Our internal HTTP API Guidelines suggest that "volatile" and "read-only" fields can cause issues with infrastructure as code providers like Terraform.

Since these meta types are read-only, I would suggest we nest them under a meta key in the response. I think I would organize the request body and response body as we see in the following examples. The user-definable properties are nested under a top-level data property to separate it from the read-only properties.

Create a dashboard

Request

POST kbn://dashboards/dashboard
{
  "title": "my dashboard",
  "description": "this is an awesome dashboard I created",
  "panels": [],
  ...rest of state keys - flatten the `attributes` key
}

Response

GET kbn://dashboards/dashboard/{id}

// response
{
  "id": "160DAB3F-1232-4C7B-8941-FF2618527178", // server-generated id
  "type": "dashboard",
  "data": {
    "title": "my dashboard",
     "description": "this is an awesome dashboard I created",
     "panels": [],
     ... rest of state keys
  },
  "meta": {
    "updated_at": "",
    "created_at": "",
    "updated_by": "",
    "created_by": "",
    "managed": "false",
  }
}

Create a dashboard with a given ID

Request

POST kbn://dashboards/dashboard/my-very-unique-id
{
  "title": "my dashboard",
  "description": "this is an awesome dashboard I created",
  "panels": [],
  ...rest of state keys - flatten the `attributes` key
}

Response

GET kbn://dashboards/dashboard/{id}

// response
{
  "id": "my-very-unique-id",
  "type": "dashboard",
  "data": {
    "title": "my dashboard",
     "description": "this is an awesome dashboard I created",
     "panels": [],
     ... rest of state keys
  },
  "meta": {
    "updated_at": "",
    "created_at": "",
    "updated_by": "",
    "created_by": "",
    "managed": "false",
  }
}

We can start by modifying the request and response bodies in the public API routes.

Once we finalize the request/response bodies in the public API routes, we can consider using those same bodies for the internal RPC routes. But that should probably be a separate PR because we would also have to update the Dashboard client and listing page to support the new bodies.