--- openapi: 3.0.3 info: title: LRA Coordinator contact: name: Narayana url: https://narayana.io version: "1.0" tags: - name: LRA Coordinator description: "Operations to work with active LRAs (to start, to get a status, to\ \ finish, etc.)" - name: LRA Recovery paths: /lra-coordinator/lra-coordinator: get: tags: - LRA Coordinator summary: Returns all LRAs description: Gets both active and recovering LRAs parameters: - name: Status in: query description: Filter the returned LRAs to only those in the give state (see CompensatorStatus) schema: default: "" type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: The LRAData json array which is known to coordinator headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: type: array items: $ref: '#/components/schemas/LRAData' "400": description: Provided Status is not recognized as a valid LRA status value headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: application/json: schema: type: string /lra-coordinator/lra-coordinator/nested/{NestedLraId}/compensate: put: tags: - LRA Coordinator parameters: - name: NestedLraId in: path required: true schema: type: string responses: "200": description: OK /lra-coordinator/lra-coordinator/nested/{NestedLraId}/complete: put: tags: - LRA Coordinator parameters: - name: NestedLraId in: path required: true schema: type: string responses: "200": description: OK /lra-coordinator/lra-coordinator/nested/{NestedLraId}/forget: put: tags: - LRA Coordinator parameters: - name: NestedLraId in: path required: true schema: type: string responses: "200": description: OK /lra-coordinator/lra-coordinator/nested/{NestedLraId}/status: get: tags: - LRA Coordinator parameters: - name: NestedLraId in: path required: true schema: type: string responses: "200": description: OK /lra-coordinator/lra-coordinator/recovery: get: tags: - LRA Recovery summary: List recovering Long Running Actions description: Returns LRAs that are recovering (ie some compensators still need to be ran) responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/LRAData' /lra-coordinator/lra-coordinator/recovery/failed: get: tags: - LRA Recovery summary: List failed Long Running Actions description: Returns LRAs that have failed. Failure records are vital pieces of data needed to aid failure tracking and analysis and are retained for inspection. responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/LRAData' /lra-coordinator/lra-coordinator/recovery/{LRAId}/{RecCoordId}: get: tags: - LRA Recovery summary: Lookup the participant URL description: Performing a GET on the recovery URL (returned from a join request) will return the original participant URL(s) parameters: - name: LRAId in: path description: Identifies the LRAId that the participant joined required: true schema: type: string - name: RecCoordId in: path description: An identifier that was returned by the coordinator when a participant joined the LRA required: true schema: type: string responses: "404": description: The coordinator has no knowledge of this participant "200": description: The participant associated with this recovery id is returned content: application/json: schema: title: The original participant URI put: tags: - LRA Recovery summary: Update the endpoint that a participant is prepared to accept requests on. description: Performing a PUT on the recovery URL will overwrite the old with the new one supplied and return the old url. The old value is returned.The full URL was returned when the participant first joined the LRA. parameters: - name: LRAId in: path description: Identifies the LRAId that the participant joined required: true schema: type: string - name: RecCoordId in: path description: An identifier that was returned by the coordinator when a participant joined the LRA required: true schema: type: string responses: "404": description: The coordinator has no knowledge of this participant "200": description: The coordinator has replaced the old participant with the new one content: application/json: schema: type: string /lra-coordinator/lra-coordinator/recovery/{LraId}: delete: tags: - LRA Recovery summary: Remove the log for a failed LRA parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string responses: "204": description: If the LRA log was successfully removed "412": description: If the input LRA does not correspond to a valid URI (in which case the response entity will contain the error message) "500": description: If the attempt to remove the LRA log failed. This return code does not discriminate between a failure at the log storage level or if the log did not exist) /lra-coordinator/lra-coordinator/start: post: tags: - LRA Coordinator summary: Start a new LRA description: "The LRA model uses a presumed nothing protocol: the coordinator\ \ must communicate with Compensators in order to inform them of the LRA activity.\ \ Every time a Compensator is enrolled with an LRA, the coordinator must make\ \ information about it durable so that the Compensator can be contacted when\ \ the LRA terminates, even in the event of subsequent failures. Compensators,\ \ clients and coordinators cannot make any presumption about the state of\ \ the global transaction without consulting the coordinator and all compensators,\ \ respectively." parameters: - name: ClientID in: query description: Each client is expected to have a unique identity (which can be a URL). required: true schema: default: "" type: string - name: ParentLRA in: query description: The enclosing LRA if this new LRA is nested schema: default: "" type: string - name: TimeLimit in: query description: "Specifies the maximum time in milli seconds that the LRA will\ \ exist for.\nIf the LRA is terminated because of a timeout, the LRA URL\ \ is deleted.\nAll further invocations on the URL will return 404.\nThe\ \ invoker can assume this was equivalent to a compensate operation." schema: format: int64 default: "0" type: integer - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "201": description: The request was successful and the response body contains the id of the new LRA headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: text/plain: schema: description: An URI of the new LRA type: string "404": description: Parent LRA id cannot be joint to the started LRA content: text/plain: schema: description: Message containing problematic LRA id type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: text/plain: schema: type: string "500": description: A new LRA could not be started. Coordinator internal error. content: text/plain: schema: type: string /lra-coordinator/lra-coordinator/{LraId}: get: tags: - LRA Coordinator summary: Obtain the information about an LRA as a JSON structure parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: The LRA exists and the information is packed as JSON in the content body. headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: $ref: '#/components/schemas/LRAData' "404": description: The coordinator has no knowledge of this LRA content: application/json: schema: type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: application/json: schema: type: string put: tags: - LRA Coordinator summary: A Compensator can join with the LRA at any time prior to the completion of an activity parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string - name: TimeLimit in: query description: "The time limit in milliseconds that the Compensator can guarantee\ \ that it can compensate the work performed by the service. After this time\ \ period has elapsed, it may no longer be possible to undo the work within\ \ the scope of this (or any enclosing) LRA. It may therefore be necessary\ \ for the application or service to start other activities to explicitly\ \ try to compensate this work. The application or coordinator may use this\ \ information to control the lifecycle of an LRA." schema: format: int64 default: 0 type: integer - name: Link in: header description: "The resource paths that the coordinator will use to complete\ \ or compensate and to request the status of the participant. The link rel\ \ names are complete, compensate and status." schema: default: "" type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' requestBody: description: opaque data that will be stored with the coordinator and passed back to the participant when the LRA is closed or cancelled. content: '*/*': schema: type: string responses: "200": description: The participant was successfully registered with the LRA headers: Long-Running-Action-Recovery: description: |- It contains a unique resource reference for that participant: - HTTP GET on the reference returns the original participant URL; - HTTP PUT on the reference will overwrite the old participant URL with the new one supplied. style: simple schema: type: string Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: description: A URI representing the recovery id of this join request type: string "400": description: Link does not contain all required fields for joining the LRA. Probably no compensator or after 'rel' is available. content: application/json: schema: type: string "404": description: The coordinator has no knowledge of this LRA content: application/json: schema: type: string "412": description: "The LRA is not longer active (ie the complete or compensate\ \ message has been sent), or wrong format of compensator data" headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: application/json: schema: type: string "500": description: Format of the compensator data (e.g. Link format) could not be processed content: application/json: schema: type: string /lra-coordinator/lra-coordinator/{LraId}/cancel: put: tags: - LRA Coordinator summary: Attempt to cancel an LRA description: " Trigger the compensation of the LRA. All compensators will be\ \ triggered by the coordinator (ie the compensate message will be sent to\ \ each compensators). Upon termination, the URL is implicitly deleted. The\ \ invoker cannot know for sure whether the lra completed or compensated without\ \ enlisting a participant." parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: The compensate message was sent to all coordinators headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: type: string "404": description: The coordinator has no knowledge of this LRA headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: application/json: schema: type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: application/json: schema: type: string /lra-coordinator/lra-coordinator/{LraId}/close: put: tags: - LRA Coordinator summary: Attempt to close an LRA description: "Trigger the successful completion of the LRA. All compensators\ \ will be dropped by the coordinator. The complete message will be sent to\ \ the compensators. Upon termination, the URL is implicitly deleted. The invoker\ \ cannot know for sure whether the lra completed or compensated without enlisting\ \ a participant." parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: The complete message was sent to all coordinators headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: text/plain: schema: type: string "404": description: The coordinator has no knowledge of this LRA headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: text/plain: schema: type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: text/plain: schema: type: string /lra-coordinator/lra-coordinator/{LraId}/remove: put: tags: - LRA Coordinator summary: A Compensator can resign from the LRA at any time prior to the completion of an activity parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: If the participant was successfully removed from the LRA headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' "400": description: The coordinator has no knowledge of this participant compensator URL content: application/json: schema: type: string "404": description: The coordinator has no knowledge of this LRA content: application/json: schema: type: string "412": description: The LRA is not longer active (ie in the complete or compensate messages have been sent "417": description: The requested version provided in HTTP Header is not supported by this end point content: application/json: schema: type: string /lra-coordinator/lra-coordinator/{LraId}/renew: put: tags: - LRA Coordinator summary: Update the TimeLimit for an existing LRA description: LRAs can be automatically cancelled if they aren't closed or cancelled before the TimeLimit specified at creation time is reached. The time limit can be updated. parameters: - name: LraId in: path description: The unique identifier of the LRA required: true schema: type: string - name: TimeLimit in: query description: The new time limit for the LRA required: true schema: format: int64 default: "0" type: integer - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: If the LRA time limit has been updated headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: {} "404": description: The coordinator has no knowledge of this LRA or the LRA is not longer active (ie the complete or compensate messages have been sent headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: {} "417": description: The requested version provided in HTTP Header is not supported by this end point content: {} /lra-coordinator/lra-coordinator/{LraId}/status: get: tags: - LRA Coordinator summary: Obtain the status of an LRA as a string parameters: - name: LraId in: path description: The unique identifier of the LRA.Expecting to be a valid URL where the participant can be contacted at. If not in URL format it will be considered to be an id which will be declared to exist at URL where coordinator is deployed at. required: true schema: type: string - $ref: '#/components/parameters/Narayana-LRA-API-version' responses: "200": description: The LRA exists. The status is reported in the content body. headers: Narayana-LRA-API-version: $ref: '#/components/headers/Narayana-LRA-API-version' content: text/plain: schema: type: string "404": description: The coordinator has no knowledge of this LRA content: text/plain: schema: type: string "417": description: The requested version provided in HTTP Header is not supported by this end point content: text/plain: schema: type: string components: schemas: LRAApiVersionSchema: description: "Format is `major.minor`, both components are required, they are\ \ to be numbers" pattern: ^\d+\.\d+$ type: string example: "1.0" LRAStatus: enum: - Active - Cancelled - Cancelling - Closed - Closing - FailedToCancel - FailedToClose type: string LRAData: type: object properties: clientId: type: string finishTime: format: int64 type: integer httpStatus: format: int32 type: integer isRecovering: type: boolean isTopLevel: type: boolean lraId: format: uri type: string startTime: format: int64 type: integer status: $ref: '#/components/schemas/LRAStatus' lraIdAsString: type: string recovering: type: boolean topLevel: type: boolean parameters: Narayana-LRA-API-version: name: Narayana-LRA-API-version in: header description: Narayana LRA API version schema: $ref: '#/components/schemas/LRAApiVersionSchema' headers: Narayana-LRA-API-version: description: Narayana LRA API version style: simple schema: $ref: '#/components/schemas/LRAApiVersionSchema'