openproject/docs/api/apiv3/paths/relation.yml

# /api/v3/relations/{id}
---
delete:
  parameters:
  - description: Relation ID
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '204':
      description: |-
        Returned if the relation was deleted successfully.
        The response body is empty.        
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to delete this relation.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** manage work package relations        
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified relation does not exist.
      description: |-
        Returned if the relation does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** manage work package relations        
      headers: {}
  tags:
  - Relations
  description: Deletes the relation.
  operationId: Delete_Relation
  summary: Delete Relation
get:
  parameters:
  - description: Relation id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _links:
                  delete:
                    href: "/api/v3/relations/1"
                    method: DELETE
                  from:
                    href: "/api/v3/work_packages/42"
                    title: Steel Delivery
                  self:
                    href: "/api/v3/relations/1"
                  to:
                    href: "/api/v3/work_packages/84"
                    title: Bending the steel
                  update:
                    href: "/api/v3/relations/1/form"
                    method: POST
                  updateImmediately:
                    href: "/api/v3/relations/1"
                    method: PATCH
                _type: Relation
                delay: 0
                description: We can't bend the steel before it's been delivered!
                id: 1
                name: precedes
                reverseType: follows
                type: precedes
          schema:
            "$ref": "../components/schemas/relation_model.yml"
      description: OK
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified relation does not exist.
      description: |-
        Returned if the relation does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** view work packages for the involved work packages        
      headers: {}
  tags:
  - Relations
  description: ''
  operationId: View_Relation
  summary: View Relation
patch:
  parameters:
  - description: Relation ID
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _links:
                  delete:
                    href: "/api/v3/relations/1"
                    method: DELETE
                  from:
                    href: "/api/v3/work_packages/42"
                    title: Steel Delivery
                  self:
                    href: "/api/v3/relations/1"
                  to:
                    href: "/api/v3/work_packages/84"
                    title: Bending the steel
                  update:
                    href: "/api/v3/relations/1/form"
                    method: POST
                  updateImmediately:
                    href: "/api/v3/relations/1"
                    method: PATCH
                _type: Relation
                delay: 0
                description: We can't bend the steel before it's been delivered!
                id: 1
                name: precedes
                reverseType: follows
                type: precedes
          schema:
            "$ref": "../components/schemas/relation_model.yml"
      description: OK
      headers: {}
    '400':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request body was not a single JSON object.
      description: Occurs when the client did not send a valid JSON object in the
        request body.
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified relation does not exist.
      description: |-
        Returned if the relation does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** manage work package relations        
      headers: {}
    '422':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: delay
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Delay must be a number greater than or equal to 0
      description: |-
        Returned if:

        * the client tries to modify a read-only property (`PropertyIsReadOnly`)

        * a constraint for a property was violated (`PropertyConstraintViolation`)

        * the client provides a link to an invalid resource (`ResourceTypeMismatch`) or a
          work package that does not exist or for which the client does not have sufficient permissions
          to see it (**required permissions**: `view work packages` for the involved work packages).        
      headers: {}
  tags:
  - Relations
  description: |-
    When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body.
    It is only allowed to provide properties or links supporting the **write** operation.

    Note that changing the `type` of a relation invariably also changes the respective `reverseType` as well as the "name" of it.
    The returned Relation object will reflect that change. For instance if you change a Relation's
    `type` to "follows" then the `reverseType` will be changed to `precedes`.    
  operationId: Edit_Relation
  summary: Edit Relation