Created
June 14, 2022 08:34
-
-
Save xstefank/a3ce61d16d02f875fb78ef714aa280af to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| --- | |
| 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: | |
| "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 | |
| "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' | |
| /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 <compensor | |
| URL> 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: | |
| "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 | |
| "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' | |
| 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: | |
| "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 | |
| "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 | |
| /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: | |
| "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 | |
| "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 | |
| /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: | |
| "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 | |
| "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 | |
| /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: | |
| "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 | |
| "200": | |
| description: If the participant was successfully removed from the LRA | |
| headers: | |
| Narayana-LRA-API-version: | |
| $ref: '#/components/headers/Narayana-LRA-API-version' | |
| /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: | |
| "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: {} | |
| "200": | |
| description: If the LRA time limit has been updated | |
| headers: | |
| Narayana-LRA-API-version: | |
| $ref: '#/components/headers/Narayana-LRA-API-version' | |
| 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: | |
| "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 | |
| "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 | |
| 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" | |
| URI: | |
| format: uri | |
| type: string | |
| 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: | |
| $ref: '#/components/schemas/URI' | |
| 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' | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment