Repository navigation
Endpoint Notes
This page outlines the general usage patterns and organization of the PEACH API. This article is intended for a technical audience, and for people who are planning on using the API endpoints.
The PEACH API is documented using the OpenAPI Specification standard:
- OpenAPI via Redocly (Human Readable)
- OpenAPI YAML (Raw YAML)
The PEACH API provides a RESTful interface for managing various resources related to PIES. One of the key principles for resource retrieval is the use of gentle fallback mechanisms.
For most endpoints, client applications should be able to retrieve resources using only the record_id for a specific record. However, in cases where just the record_id is not sufficient (e.g., when multiple records share the same ID), additional query parameters like system_id will be required to disambiguate the request.
---
title: Recommended Client Record Retrieval Flow
---
graph LR
C1@{ shape: diamond, label: "Response" }
C2@{ shape: diamond, label: "Response" }
EN@{ shape: fr-circ, label: "End" }
RR@{ shape: lean-r, label: "Try with record_id only" }
RS@{ shape: lean-r, label: "Try with record_id and system_id" }
ST@{ shape: sm-circ, label: "Start" }
ST -- Partial Search --> RR
ST -- Canonical Search --> RS
RR --> C1
C1 -- HTTP 2XX --> EN
C1 -- HTTP 404 --> EN
C1 -- HTTP 409 --> RS
RS --> C2
C2 -- HTTP 2XX --> EN
C2 -- HTTP 404 --> EN
C2 -- HTTP 409 --> EN
Client applications will know when disambiguation is required when the request yields an HTTP 409 Conflict response. Clients are strongly encouraged to handle this gracefully, either by always providing the system_id when retrieving records or by implementing logic to handle conflicts and retrying with the appropriate parameter expansion.
Warning
Behavior in this section is not finalized and may change over time
Operations for managing Assets. May potentially proxy to JIRA API.
-
Endpoint:
GET /assets - Description: Get a specific asset header
This endpoint retrieves the header information for a specific asset. The response body should comply with the Header data element definition. The main purpose of this endpoint is to provide a quick overview of the asset's metadata, and also doubles as a way to check if the asset exists in the system.
-
Endpoint:
DELETE /assets - Description: Deletes a specific Asset.
This endpoint is used to delete a specific asset from the system. It allows clients to remove an asset and all its associated data from the PEACH API. The request should identify the asset to be deleted, and the operation will remove it from the system entirely. This operation is irreversible and should be used with caution, as it will permanently delete the asset and all its associated data.
Warning
Behavior in this section is not finalized and may change over time
Operations for managing Record Linkages.
-
Endpoint:
GET /record-linkages - Description: Retrieves a flattened set of all known RecordLinkages associated with a record.
This endpoint focuses on retrieving all RecordLinkages associated with a specific record, optionally limiting traversal depth in the graph. The response body should yield an array of RecordLinkage message elements.
Please check the notes on Record Identification for more details on how to properly query for records.
-
Endpoint:
PUT /record-linkages - Description: Adds RecordLinkages associated with a record.
This endpoint is used to add new RecordLinkages to a specific record. It allows clients to associate additional records with the current record, enhancing the relationships and connections between different records in different systems. The request body should comply with the RecordLinkage message element definition.
Please check the notes on Record Identification for more details on how to properly query for records.
Note
This endpoint supports an accompanying validation endpoint at PUT /record-linkages/validate which allows clients to
validate their request body before making the actual request. This is particularly useful for clients that want to
ensure their request will succeed before making changes to the system.
-
Endpoint:
DELETE /record-linkages - Description: Deletes a linkage between two specific records (requires both record and linked_record identifiers).
This endpoint is used to delete a specific RecordLinkage associated with a record. It allows clients to remove the association between two records, effectively severing the link between them. The request should identify the two records that are linked together, and the request will remove the linkage between them. This operation is useful for maintaining the integrity of record relationships and ensuring that only relevant linkages are retained.
Please check the notes on Record Identification for more details on how to properly query for records.
Operations for managing Records.
-
Endpoint:
GET /records - Description: Retrieves a set of all known Events associated with a record.
This endpoint focuses on retrieving all Events associated with a specific record. The response body should comply with the Record message element definition.
Please check the notes on Record Identification for more details on how to properly query for records.
-
Endpoint:
POST /records - Description: Adds and merges all known Events associated with a record.
This endpoint is used to add and modify new Events to a specific record. It allows clients to submit a set of Events that should be associated with the record. The request body should comply with the Record message element definition.
When using this endpoint, the client may provide an incomplete set of Events. The server will attempt to merge the provided events with the existing ones, ensuring that any new events are added and existing ones are updated as necessary. Refer to the Merge Algorithm for more details on how merging is handled.
Note
This endpoint supports an accompanying validation endpoint at POST /records/validate which allows clients to
validate their request body before making the actual request. This is particularly useful for clients that want to
ensure their request will succeed before making changes to the system.
-
Endpoint:
PUT /records - Description: Replaces all known Events associated with a record.
This endpoint is used to assert the current state of Events associated with a record. It replaces all existing Events with the provided set, ensuring that the record reflects the latest state of its associated processes. This operation is idempotent, meaning that multiple identical requests will have the same effect as a single request. The request body should comply with the Record message element definition.
When using this endpoint, the client should ensure that the provided set of Events is complete and accurate, as it will overwrite any existing events. This is particularly useful in scenarios where a record needs to be reset or updated with a new canonical set of events as sent by the client.
Note
This endpoint supports an accompanying validation endpoint at PUT /records/validate which allows clients to
validate their request body before making the actual request. This is particularly useful for clients that want to
ensure their request will succeed before making changes to the system.
-
Endpoint:
DELETE /records - Description: Deletes all known Events associated with a record.
This endpoint will prune all Events associated with a specific record. It is intended for use in scenarios where a record needs to be reset or cleared of all associated events. Note that this operation is irreversible and should be used with caution. This operation will not delete the record itself, only its associated events.
Please check the notes on Record Identification for more details on how to properly query for records.
Warning
Behavior in this section is not finalized and may change over time
Operations for managing Systems. May potentially proxy to JIRA API.
-
Endpoint:
GET /systems - Description: Checks if a specific system has records being tracked. Returns true if the system is being tracked, false if system is known but not tracked, 404 if not found in JIRA ITSM (TBD in scope?).
This endpoint behaves as a predicate to determine if a specific system is being tracked by the PEACH API. It returns a boolean value indicating whether the system has records associated with it. If the system is known but not currently tracked, it will return false. If the system is not found in the JIRA ITSM, it will return a 404 Not Found response.
Return Home