diff --git a/openapi/components/parameters/ID.yaml b/openapi/components/parameters/ID.yaml new file mode 100644 index 0000000..9d15387 --- /dev/null +++ b/openapi/components/parameters/ID.yaml @@ -0,0 +1,6 @@ +name: id +in: path +required: true +description: ID of the record - a path refuses its URL +schema: + $ref: '#/components/schemas/ResourceID' diff --git a/openapi/components/parameters/UserID.yaml b/openapi/components/parameters/UserID.yaml new file mode 100644 index 0000000..9d55dc2 --- /dev/null +++ b/openapi/components/parameters/UserID.yaml @@ -0,0 +1,6 @@ +name: user_id +in: path +required: true +description: ID of the user - a path refuses its URL +schema: + $ref: '#/components/schemas/ResourceID' diff --git a/openapi/components/parameters/UserId.yaml b/openapi/components/parameters/UserId.yaml deleted file mode 100644 index f7d4f7b..0000000 --- a/openapi/components/parameters/UserId.yaml +++ /dev/null @@ -1,7 +0,0 @@ -name: user_id -in: path -required: true -description: ID of the user -schema: - type: string - example: '32382' diff --git a/openapi/components/schemas/AttachmentUpdatePayload.yaml b/openapi/components/schemas/AttachmentUpdatePayload.yaml index fd31ddc..79f0739 100644 --- a/openapi/components/schemas/AttachmentUpdatePayload.yaml +++ b/openapi/components/schemas/AttachmentUpdatePayload.yaml @@ -3,8 +3,7 @@ required: - url properties: url: - type: string - example: https://api.freeagent.com/v2/attachments/1 + $ref: '#/components/schemas/ResourceID' data: type: string description: Binary data of the file encoded as base64 diff --git a/openapi/components/schemas/BankTransactionExplanationCreatePayload.yaml b/openapi/components/schemas/BankTransactionExplanationCreatePayload.yaml index 7fb6b9e..1c7d345 100644 --- a/openapi/components/schemas/BankTransactionExplanationCreatePayload.yaml +++ b/openapi/components/schemas/BankTransactionExplanationCreatePayload.yaml @@ -3,14 +3,11 @@ properties: attachment: $ref: '#/components/schemas/AttachmentPayload' bank_account: - type: string - example: https://api.freeagent.com/v2/bank_accounts/1 + $ref: '#/components/schemas/ResourceID' bank_transaction: - type: string - example: https://api.freeagent.com/v2/bank_transactions/8 + $ref: '#/components/schemas/ResourceID' category: - type: string - example: https://api.freeagent.com/v2/categories/285 + $ref: '#/components/schemas/ResourceID' dated_on: type: string example: 2010-05-01 @@ -21,17 +18,13 @@ properties: type: string example: '-730.0' paid_bill: - type: string - example: https://api.freeagent.com/v2/bills/123 + $ref: '#/components/schemas/ResourceID' paid_invoice: - type: string - example: https://api.freeagent.com/v2/invoices/123 + $ref: '#/components/schemas/ResourceID' paid_user: - type: string - example: https://api.freeagent.com/v2/users/1 + $ref: '#/components/schemas/ResourceID' project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' rebill_factor: type: string example: '0.25' diff --git a/openapi/components/schemas/BankTransactionExplanationUpdatePayload.yaml b/openapi/components/schemas/BankTransactionExplanationUpdatePayload.yaml index db04390..e4da256 100644 --- a/openapi/components/schemas/BankTransactionExplanationUpdatePayload.yaml +++ b/openapi/components/schemas/BankTransactionExplanationUpdatePayload.yaml @@ -3,8 +3,7 @@ properties: attachment: $ref: '#/components/schemas/AttachmentPayload' category: - type: string - example: https://api.freeagent.com/v2/categories/285 + $ref: '#/components/schemas/ResourceID' description: type: string example: Updated description @@ -12,11 +11,9 @@ properties: type: string example: '-730.0' paid_bill: - type: string - example: https://api.freeagent.com/v2/bills/123 + $ref: '#/components/schemas/ResourceID' paid_user: - type: string - example: https://api.freeagent.com/v2/users/1 + $ref: '#/components/schemas/ResourceID' sales_tax_rate: type: string example: '0.0' diff --git a/openapi/components/schemas/BillCreatePayload.yaml b/openapi/components/schemas/BillCreatePayload.yaml index e3a0311..de87313 100644 --- a/openapi/components/schemas/BillCreatePayload.yaml +++ b/openapi/components/schemas/BillCreatePayload.yaml @@ -6,8 +6,7 @@ required: - due_on properties: contact: - type: string - example: https://api.freeagent.com/v2/contacts/1 + $ref: '#/components/schemas/ResourceID' reference: type: string example: REF100 @@ -21,8 +20,7 @@ properties: type: string example: Vehicle purchase project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' recurring: $ref: '#/components/schemas/BillRecurringPeriod' recurring_end_date: diff --git a/openapi/components/schemas/BillItemPayload.yaml b/openapi/components/schemas/BillItemPayload.yaml index 5fda302..2c59798 100644 --- a/openapi/components/schemas/BillItemPayload.yaml +++ b/openapi/components/schemas/BillItemPayload.yaml @@ -1,16 +1,14 @@ type: object properties: url: - type: string - description: On update, the URL or ID of an existing item to update or remove, or an empty string to add one - FreeAgent rejects an item without it - example: https://api.freeagent.com/v2/bill_items/1 + $ref: '#/components/schemas/ResourceID' + description: On update, the existing item to update or remove, or an empty string to add one - FreeAgent rejects an item without it _destroy: type: integer description: Set to 1, with url, to remove the item example: 1 category: - type: string - example: https://api.freeagent.com/v2/categories/285 + $ref: '#/components/schemas/ResourceID' description: type: string example: Item description diff --git a/openapi/components/schemas/BillUpdatePayload.yaml b/openapi/components/schemas/BillUpdatePayload.yaml index e7fd5c9..33703b2 100644 --- a/openapi/components/schemas/BillUpdatePayload.yaml +++ b/openapi/components/schemas/BillUpdatePayload.yaml @@ -1,8 +1,7 @@ type: object properties: contact: - type: string - example: https://api.freeagent.com/v2/contacts/1 + $ref: '#/components/schemas/ResourceID' reference: type: string example: REF100 @@ -17,8 +16,7 @@ properties: description: An empty string removes the comments example: Annual hosting project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' recurring: $ref: '#/components/schemas/BillRecurringPeriod' recurring_end_date: diff --git a/openapi/components/schemas/CreditNoteCreatePayload.yaml b/openapi/components/schemas/CreditNoteCreatePayload.yaml index 7a8bf13..f10c8e6 100644 --- a/openapi/components/schemas/CreditNoteCreatePayload.yaml +++ b/openapi/components/schemas/CreditNoteCreatePayload.yaml @@ -4,11 +4,9 @@ required: - dated_on properties: contact: - type: string - example: https://api.freeagent.com/v2/contacts/1 + $ref: '#/components/schemas/ResourceID' project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' dated_on: type: string example: '2026-10-02' diff --git a/openapi/components/schemas/CreditNoteItemPayload.yaml b/openapi/components/schemas/CreditNoteItemPayload.yaml index b7d5f10..a1014d1 100644 --- a/openapi/components/schemas/CreditNoteItemPayload.yaml +++ b/openapi/components/schemas/CreditNoteItemPayload.yaml @@ -2,7 +2,7 @@ type: object properties: id: type: string - description: ID of an existing item to update or remove - the docs say integer, and a string is accepted too + description: ID of an existing item to update or remove, not its URL, which is a 404 - the docs say integer, and a string is accepted too example: '1' _destroy: type: integer diff --git a/openapi/components/schemas/EstimateCreatePayload.yaml b/openapi/components/schemas/EstimateCreatePayload.yaml index bf64cff..a327833 100644 --- a/openapi/components/schemas/EstimateCreatePayload.yaml +++ b/openapi/components/schemas/EstimateCreatePayload.yaml @@ -5,11 +5,9 @@ required: - status properties: contact: - type: string - example: https://api.freeagent.com/v2/contacts/1 + $ref: '#/components/schemas/ResourceID' project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' dated_on: type: string example: '2026-10-02' diff --git a/openapi/components/schemas/ExpenseCreatePayload.yaml b/openapi/components/schemas/ExpenseCreatePayload.yaml index d43dc9a..94d21cd 100644 --- a/openapi/components/schemas/ExpenseCreatePayload.yaml +++ b/openapi/components/schemas/ExpenseCreatePayload.yaml @@ -6,12 +6,10 @@ required: - description properties: user: - type: string - example: https://api.freeagent.com/v2/users/1 + $ref: '#/components/schemas/ResourceID' category: - type: string + $ref: '#/components/schemas/ResourceID' description: The Mileage category (249) makes a mileage claim, which takes mileage and vehicle_type in place of gross_value - example: https://api.freeagent.com/v2/categories/285 dated_on: type: string example: 2026-09-15 @@ -38,8 +36,7 @@ properties: type: string example: REC-001 project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' rebill_type: $ref: '#/components/schemas/ExpenseRebillType' rebill_factor: diff --git a/openapi/components/schemas/ExpenseUpdatePayload.yaml b/openapi/components/schemas/ExpenseUpdatePayload.yaml index b01cb8d..e3b2fc0 100644 --- a/openapi/components/schemas/ExpenseUpdatePayload.yaml +++ b/openapi/components/schemas/ExpenseUpdatePayload.yaml @@ -1,11 +1,9 @@ type: object properties: user: - type: string - example: https://api.freeagent.com/v2/users/1 + $ref: '#/components/schemas/ResourceID' category: - type: string - example: https://api.freeagent.com/v2/categories/285 + $ref: '#/components/schemas/ResourceID' dated_on: type: string example: 2026-09-15 @@ -32,8 +30,7 @@ properties: description: An empty string removes the receipt reference example: REC-001 project: - type: string - example: https://api.freeagent.com/v2/projects/1 + $ref: '#/components/schemas/ResourceID' rebill_type: $ref: '#/components/schemas/ExpenseRebillType' rebill_factor: diff --git a/openapi/components/schemas/InvoiceCreatePayload.yaml b/openapi/components/schemas/InvoiceCreatePayload.yaml index 63032f8..12efa0e 100644 --- a/openapi/components/schemas/InvoiceCreatePayload.yaml +++ b/openapi/components/schemas/InvoiceCreatePayload.yaml @@ -4,12 +4,10 @@ properties: type: boolean example: false contact: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' project: - type: string + $ref: '#/components/schemas/ResourceID' description: Must belong to the contact, or the create is a 422 - example: https://api.freeagent.com/v2/projects/:id include_timeslips: type: string description: Bills every unbilled timeslip on the project onto the invoice, grouped as named - without a project nothing is billed diff --git a/openapi/components/schemas/JournalEntryPayload.yaml b/openapi/components/schemas/JournalEntryPayload.yaml index eb1174a..80ba07e 100644 --- a/openapi/components/schemas/JournalEntryPayload.yaml +++ b/openapi/components/schemas/JournalEntryPayload.yaml @@ -2,17 +2,15 @@ type: object additionalProperties: false properties: url: - type: string - description: On update, the URL or ID of an existing entry to update or remove - left out, the entry is added - example: https://api.freeagent.com/v2/journal_sets/1/journal_entries/1 + $ref: '#/components/schemas/ResourceID' + description: On update, the existing entry to update or remove - left out, the entry is added _destroy: type: boolean description: Set to true, with url, to remove the entry example: true category: - type: string - description: The category URL or nominal code - an unknown code is a 400 - example: https://api.freeagent.com/v2/categories/901 + $ref: '#/components/schemas/ResourceID' + description: The category, whose ID is its nominal code - an unknown code is a 400 debit_value: type: number description: Negative for a credit - rounded to two places, and 0 when left out @@ -21,13 +19,11 @@ properties: type: string example: Director's capital introduced user: - type: string + $ref: '#/components/schemas/ResourceID' description: Needed for user categories such as 901 and 907, or the request is a 404 - ignored on other categories - example: https://api.freeagent.com/v2/users/1 capital_asset_type: - type: string + $ref: '#/components/schemas/ResourceID' description: Needed for capital asset categories 601 to 607, or the request is a 404 - example: https://api.freeagent.com/v2/capital_asset_types/1 stock_item: type: string description: For stock categories @@ -41,6 +37,5 @@ properties: description: For unincorporated landlords, on profit and loss categories example: https://api.freeagent.com/v2/properties/1 contact: - type: string + $ref: '#/components/schemas/ResourceID' description: Opening balances only, for Trade Debtors (681) and Trade Creditors (796) - a 422 on any other set - example: https://api.freeagent.com/v2/contacts/1 diff --git a/openapi/components/schemas/ProjectCreatePayload.yaml b/openapi/components/schemas/ProjectCreatePayload.yaml index 42d12d9..fa5ef7d 100644 --- a/openapi/components/schemas/ProjectCreatePayload.yaml +++ b/openapi/components/schemas/ProjectCreatePayload.yaml @@ -7,8 +7,7 @@ required: - budget_units properties: contact: - type: string - example: https://api.freeagent.com/v2/contacts/1 + $ref: '#/components/schemas/ResourceID' name: type: string example: Website Development diff --git a/openapi/components/schemas/ProjectUpdatePayload.yaml b/openapi/components/schemas/ProjectUpdatePayload.yaml index f68ae30..e2ffe03 100644 --- a/openapi/components/schemas/ProjectUpdatePayload.yaml +++ b/openapi/components/schemas/ProjectUpdatePayload.yaml @@ -2,8 +2,7 @@ type: object description: Fields left out are kept - an empty contract_po_reference, starts_on or ends_on removes it properties: contact: - type: string - example: https://api.freeagent.com/v2/contacts/1 + $ref: '#/components/schemas/ResourceID' name: type: string example: Website Development diff --git a/openapi/components/schemas/ResourceID.yaml b/openapi/components/schemas/ResourceID.yaml new file mode 100644 index 0000000..0c5fccd --- /dev/null +++ b/openapi/components/schemas/ResourceID.yaml @@ -0,0 +1,3 @@ +type: string +description: A record's URL or its ID +example: '1' diff --git a/openapi/components/schemas/TimeslipCreatePayload.yaml b/openapi/components/schemas/TimeslipCreatePayload.yaml index 26794bd..e44bddf 100644 --- a/openapi/components/schemas/TimeslipCreatePayload.yaml +++ b/openapi/components/schemas/TimeslipCreatePayload.yaml @@ -5,15 +5,12 @@ required: - dated_on properties: user: - type: string - example: https://api.freeagent.com/v2/users/1 + $ref: '#/components/schemas/ResourceID' project: - type: string + $ref: '#/components/schemas/ResourceID' description: Documented as required, but FreeAgent always uses the task's project and ignores this - example: https://api.freeagent.com/v2/projects/1 task: - type: string - example: https://api.freeagent.com/v2/tasks/1 + $ref: '#/components/schemas/ResourceID' dated_on: type: string example: '2026-10-02' diff --git a/openapi/components/schemas/TimeslipUpdatePayload.yaml b/openapi/components/schemas/TimeslipUpdatePayload.yaml index dc042b3..7666dd0 100644 --- a/openapi/components/schemas/TimeslipUpdatePayload.yaml +++ b/openapi/components/schemas/TimeslipUpdatePayload.yaml @@ -1,11 +1,9 @@ type: object properties: user: - type: string - example: https://api.freeagent.com/v2/users/1 + $ref: '#/components/schemas/ResourceID' task: - type: string - example: https://api.freeagent.com/v2/tasks/1 + $ref: '#/components/schemas/ResourceID' dated_on: type: string example: '2026-10-02' diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index bbca93d..49495ac 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.3 +openapi: 3.1.0 info: title: FreeAgent version: '2026-09-01' @@ -295,6 +295,8 @@ components: $ref: 'components/schemas/ProjectCreatePayload.yaml' ProjectUpdatePayload: $ref: 'components/schemas/ProjectUpdatePayload.yaml' + ResourceID: + $ref: 'components/schemas/ResourceID.yaml' Currency: $ref: 'components/schemas/Currency.yaml' ProjectStatus: @@ -478,8 +480,10 @@ components: $ref: 'components/parameters/PeriodEndsOn.yaml' PaymentDate: $ref: 'components/parameters/PaymentDate.yaml' - UserId: - $ref: 'components/parameters/UserId.yaml' + ID: + $ref: 'components/parameters/ID.yaml' + UserID: + $ref: 'components/parameters/UserID.yaml' headers: Link: $ref: 'components/headers/Link.yaml' diff --git a/openapi/paths/attachments.yaml b/openapi/paths/attachments.yaml index 76cfdde..5f59471 100644 --- a/openapi/paths/attachments.yaml +++ b/openapi/paths/attachments.yaml @@ -26,9 +26,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/bank_accounts.yaml b/openapi/paths/bank_accounts.yaml index 0f1e8e6..0173452 100644 --- a/openapi/paths/bank_accounts.yaml +++ b/openapi/paths/bank_accounts.yaml @@ -44,9 +44,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/bank_transaction_explanation_attachments.yaml b/openapi/paths/bank_transaction_explanation_attachments.yaml index ea64083..c3a35ca 100644 --- a/openapi/paths/bank_transaction_explanation_attachments.yaml +++ b/openapi/paths/bank_transaction_explanation_attachments.yaml @@ -55,9 +55,4 @@ list: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/bank_transaction_explanations.yaml b/openapi/paths/bank_transaction_explanations.yaml index aa1f098..d669687 100644 --- a/openapi/paths/bank_transaction_explanations.yaml +++ b/openapi/paths/bank_transaction_explanations.yaml @@ -25,8 +25,7 @@ list: in: query required: true schema: - type: string - example: https://api.freeagent.com/v2/bank_accounts/:id + $ref: '#/components/schemas/ResourceID' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: @@ -134,9 +133,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/bank_transactions.yaml b/openapi/paths/bank_transactions.yaml index d8ace0d..99f10df 100644 --- a/openapi/paths/bank_transactions.yaml +++ b/openapi/paths/bank_transactions.yaml @@ -10,8 +10,7 @@ list: in: query required: true schema: - type: string - example: https://api.freeagent.com/v2/bank_accounts/1 + $ref: '#/components/schemas/ResourceID' - name: from_date in: query schema: @@ -70,9 +69,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/bills.yaml b/openapi/paths/bills.yaml index 3e2cbab..4c27772 100644 --- a/openapi/paths/bills.yaml +++ b/openapi/paths/bills.yaml @@ -14,16 +14,14 @@ list: example: true - name: contact in: query - description: Filter bills by contact URL - an unknown contact matches nothing + description: Filter bills by contact - an unknown contact matches nothing schema: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' - name: project in: query - description: Filter bills by project URL + description: Filter bills by project schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: view in: query description: Filter bills by view - FreeAgent answers an unknown view with a 400 @@ -195,9 +193,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/contacts.yaml b/openapi/paths/contacts.yaml index 2b8643b..5f294c6 100644 --- a/openapi/paths/contacts.yaml +++ b/openapi/paths/contacts.yaml @@ -145,9 +145,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/credit_notes.yaml b/openapi/paths/credit_notes.yaml index 4c93de1..d27248d 100644 --- a/openapi/paths/credit_notes.yaml +++ b/openapi/paths/credit_notes.yaml @@ -14,16 +14,14 @@ list: example: true - name: contact in: query - description: Filter credit notes by contact URL + description: Filter credit notes by contact schema: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' - name: project in: query - description: Filter credit notes by project URL + description: Filter credit notes by project schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: view in: query description: Filter credit notes by view - FreeAgent answers an unknown view with a 400 @@ -178,12 +176,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' pdf: get: tags: @@ -201,12 +194,7 @@ pdf: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' send_email: post: tags: @@ -242,12 +230,7 @@ send_email: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_sent: put: tags: @@ -266,12 +249,7 @@ mark_as_sent: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_draft: put: tags: @@ -290,9 +268,4 @@ mark_as_draft: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/estimates.yaml b/openapi/paths/estimates.yaml index 3e836d2..1344ae0 100644 --- a/openapi/paths/estimates.yaml +++ b/openapi/paths/estimates.yaml @@ -14,22 +14,19 @@ list: example: true - name: contact in: query - description: Filter estimates by contact URL + description: Filter estimates by contact schema: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' - name: project in: query - description: Filter estimates by project URL + description: Filter estimates by project schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: invoice in: query - description: Filter estimates by the URL of the invoice they were converted to + description: Filter estimates by the invoice they were converted to schema: - type: string - example: https://api.freeagent.com/v2/invoices/:id + $ref: '#/components/schemas/ResourceID' - name: view in: query description: Filter estimates by view - FreeAgent returns no estimates for an unknown view rather than an error @@ -170,12 +167,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' pdf: get: tags: @@ -193,12 +185,7 @@ pdf: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' send_email: post: tags: @@ -234,12 +221,7 @@ send_email: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' duplicate: post: tags: @@ -257,12 +239,7 @@ duplicate: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_sent: put: tags: @@ -281,12 +258,7 @@ mark_as_sent: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_draft: put: tags: @@ -305,12 +277,7 @@ mark_as_draft: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_approved: put: tags: @@ -329,12 +296,7 @@ mark_as_approved: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_rejected: put: tags: @@ -353,12 +315,7 @@ mark_as_rejected: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' convert_to_invoice: put: tags: @@ -377,12 +334,7 @@ convert_to_invoice: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' create_item: post: tags: @@ -400,8 +352,7 @@ create_item: - estimate_item properties: estimate: - type: string - example: https://api.freeagent.com/v2/estimates/1 + $ref: '#/components/schemas/ResourceID' estimate_item: $ref: '#/components/schemas/EstimateItemPayload' examples: @@ -465,9 +416,4 @@ update_item: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/expenses.yaml b/openapi/paths/expenses.yaml index 1409ebd..69294a0 100644 --- a/openapi/paths/expenses.yaml +++ b/openapi/paths/expenses.yaml @@ -35,16 +35,14 @@ list: example: 2026-01-01T00:00:00Z - name: project in: query - description: Filter expenses by project URL - an unknown project is a 404 + description: Filter expenses by project - an unknown project is a 404 schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: user in: query - description: Filter expenses by claimant URL - not documented, and an unknown user matches nothing + description: Filter expenses by claimant - not documented, and an unknown user matches nothing schema: - type: string - example: https://api.freeagent.com/v2/users/:id + $ref: '#/components/schemas/ResourceID' - name: sort in: query description: Sort expenses by specified field, descending with a leading hyphen - not documented @@ -201,12 +199,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mileage_settings: get: tags: diff --git a/openapi/paths/invoices.yaml b/openapi/paths/invoices.yaml index f124b5a..f1b5efe 100644 --- a/openapi/paths/invoices.yaml +++ b/openapi/paths/invoices.yaml @@ -16,12 +16,7 @@ mark_as_sent: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_cancelled: put: tags: @@ -40,12 +35,7 @@ mark_as_cancelled: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_scheduled: put: tags: @@ -64,12 +54,7 @@ mark_as_scheduled: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' mark_as_draft: put: tags: @@ -88,12 +73,7 @@ mark_as_draft: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' list: get: tags: @@ -110,16 +90,14 @@ list: example: true - name: contact in: query - description: Filter invoices by contact URL + description: Filter invoices by contact schema: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' - name: project in: query - description: Filter invoices by project URL + description: Filter invoices by project schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: currency in: query description: Filter invoices by currency code @@ -267,12 +245,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' timeline: get: tags: @@ -306,12 +279,7 @@ pdf: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' send_email: post: tags: @@ -345,12 +313,7 @@ send_email: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' create_item: post: tags: @@ -365,8 +328,7 @@ create_item: type: object properties: invoice: - type: string - example: https://api.freeagent.com/v2/invoices/1 + $ref: '#/components/schemas/ResourceID' invoice_item: $ref: '#/components/schemas/InvoiceItemPayload' examples: @@ -428,9 +390,4 @@ update_item: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/journal_sets.yaml b/openapi/paths/journal_sets.yaml index 8a0fe8e..67920e4 100644 --- a/openapi/paths/journal_sets.yaml +++ b/openapi/paths/journal_sets.yaml @@ -164,9 +164,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/projects.yaml b/openapi/paths/projects.yaml index 3befcea..9a3079c 100644 --- a/openapi/paths/projects.yaml +++ b/openapi/paths/projects.yaml @@ -37,10 +37,9 @@ list: example: -updated_at - name: contact in: query - description: Filter projects by contact URL - an unknown contact is a 404 + description: Filter projects by contact - an unknown contact is a 404 schema: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: @@ -149,9 +148,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/recurring_invoices.yaml b/openapi/paths/recurring_invoices.yaml index e3d125a..34fd109 100644 --- a/openapi/paths/recurring_invoices.yaml +++ b/openapi/paths/recurring_invoices.yaml @@ -18,10 +18,9 @@ list: example: draft - name: contact in: query - description: Filter by contact URL + description: Filter by contact schema: - type: string - example: https://api.freeagent.com/v2/contacts/:id + $ref: '#/components/schemas/ResourceID' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' responses: @@ -55,9 +54,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/self_assessment_returns.yaml b/openapi/paths/self_assessment_returns.yaml index 35c7e14..666db23 100644 --- a/openapi/paths/self_assessment_returns.yaml +++ b/openapi/paths/self_assessment_returns.yaml @@ -15,7 +15,7 @@ list: default: $ref: '#/components/responses/ErrorResponse' parameters: - - $ref: '#/components/parameters/UserId' + - $ref: '#/components/parameters/UserID' show: get: tags: @@ -33,7 +33,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - $ref: '#/components/parameters/UserId' + - $ref: '#/components/parameters/UserID' - $ref: '#/components/parameters/PeriodEndsOn' mark_as_filed: put: @@ -52,7 +52,7 @@ mark_as_filed: default: $ref: '#/components/responses/ErrorResponse' parameters: - - $ref: '#/components/parameters/UserId' + - $ref: '#/components/parameters/UserID' - $ref: '#/components/parameters/PeriodEndsOn' mark_as_unfiled: put: @@ -71,7 +71,7 @@ mark_as_unfiled: default: $ref: '#/components/responses/ErrorResponse' parameters: - - $ref: '#/components/parameters/UserId' + - $ref: '#/components/parameters/UserID' - $ref: '#/components/parameters/PeriodEndsOn' mark_payment_as_paid: put: @@ -90,7 +90,7 @@ mark_payment_as_paid: default: $ref: '#/components/responses/ErrorResponse' parameters: - - $ref: '#/components/parameters/UserId' + - $ref: '#/components/parameters/UserID' - $ref: '#/components/parameters/PeriodEndsOn' - $ref: '#/components/parameters/PaymentDate' mark_payment_as_unpaid: @@ -110,6 +110,6 @@ mark_payment_as_unpaid: default: $ref: '#/components/responses/ErrorResponse' parameters: - - $ref: '#/components/parameters/UserId' + - $ref: '#/components/parameters/UserID' - $ref: '#/components/parameters/PeriodEndsOn' - $ref: '#/components/parameters/PaymentDate' diff --git a/openapi/paths/tasks.yaml b/openapi/paths/tasks.yaml index 5c7de33..71bbac3 100644 --- a/openapi/paths/tasks.yaml +++ b/openapi/paths/tasks.yaml @@ -36,10 +36,9 @@ list: example: -updated_at - name: project in: query - description: Filter tasks by project URL - an unknown project is a 404 + description: Filter tasks by project - an unknown project is a 404 schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: updated_since in: query description: Show tasks updated since this date or timestamp - FreeAgent answers an invalid one with a 400 @@ -72,10 +71,9 @@ list: - name: project in: query required: true - description: The project URL or ID - an unknown project is a 404 + description: The project - an unknown project is a 404 schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' requestBody: content: application/json: @@ -160,9 +158,4 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/timeslips.yaml b/openapi/paths/timeslips.yaml index e68570d..f9980f0 100644 --- a/openapi/paths/timeslips.yaml +++ b/openapi/paths/timeslips.yaml @@ -8,22 +8,19 @@ list: parameters: - name: user in: query - description: Filter timeslips by user URL + description: Filter timeslips by user schema: - type: string - example: https://api.freeagent.com/v2/users/:id + $ref: '#/components/schemas/ResourceID' - name: project in: query - description: Filter timeslips by project URL - an unknown project is a 404 + description: Filter timeslips by project - an unknown project is a 404 schema: - type: string - example: https://api.freeagent.com/v2/projects/:id + $ref: '#/components/schemas/ResourceID' - name: task in: query - description: Filter timeslips by task URL - an unknown task is a 404 + description: Filter timeslips by task - an unknown task is a 404 schema: - type: string - example: https://api.freeagent.com/v2/tasks/:id + $ref: '#/components/schemas/ResourceID' - name: view in: query description: Filter timeslips by view - unbilled leaves out timeslips billed on an invoice, and FreeAgent answers an unknown view with a 400 @@ -175,12 +172,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' timer: post: tags: @@ -215,9 +207,4 @@ timer: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' diff --git a/openapi/paths/users.yaml b/openapi/paths/users.yaml index eb69ee3..1cdeb65 100644 --- a/openapi/paths/users.yaml +++ b/openapi/paths/users.yaml @@ -127,12 +127,7 @@ show: default: $ref: '#/components/responses/ErrorResponse' parameters: - - name: id - in: path - required: true - schema: - type: string - example: '' + - $ref: '#/components/parameters/ID' me: get: tags: