Skip to content

GraphQL API Calling Obligations (Content Mutations)

This document defines client obligations when calling the marketing GraphQL BFF.

Scope

  • Content domains:
  • Article
  • ArticleCollection
  • Product
  • ProductCollection
  • Operations:
  • create/update/delete
  • relationship updates (for example collection membership)

Caller Obligations

  1. Use BFF as the only mutation path

  2. Do not mutate Odoo content directly from client applications.

  3. Provide domain payload only

  4. Send only business/content fields required by the mutation contract.

  5. Do not send internal audit identity fields.

  6. Use stable identifiers consistently

  7. Prefer canonical keys (articleKey, productKey, collectionKey) from BFF responses.

  8. Do not infer IDs across types.

  9. Preserve idempotency and retry safety

  10. Use deterministic keys/slugs where contract allows.

  11. Handle network retries without creating duplicate logical records.

  12. Enforce schema correctness

  13. Match exact GraphQL scalar types expected by server.
  14. Example: if a mutation expects [Int!]!, do not send [String!]!.

Forbidden Input Fields

Clients must not send these as authoritative values in mutation payloads:

  • createdBy
  • updatedBy
  • createdAt
  • updatedAt

These are server-managed by BFF and mapped into Odoo audit records.

Response Consumption Requirements

  • Treat server-returned audit fields as authoritative.
  • For post-mutation state checks, compare returned entity keys and updatedAt/updatedBy values.

Error Handling Requirements

  • On validation/type errors, do not silently coerce and retry with guessed schema.
  • Log the exact GraphQL error and correct the request contract first.

Security and Accountability

  • Caller authentication must be present for all mutation operations.
  • BFF resolves actor from auth context and stamps audit fields server-side.
  • Real credential identity is operational/internal and not a public content attribute.