Building APIs

A brief introduction to the purpose of the documentation, focusing on building front-end APIs that interact with Odoo.

Understading api requests

GET: In Odoo, GET requests from the client are handled using queries. POST and Other HTTP Verbs: All other operations (POST, PUT, DELETE) are handled as mutations

Types and Data Structures

Whenever a query or mutation is made, there is an associated type on client side with Odoo type. The client side type represents the expected response format from the Odoo server side.

These response types are defined in a file named types.ts, located in the /graphql directory.

They are created by observing the return of the query or mutation and structured to ensure that the client side can process the response properly.

Example: For a query that returns cart information, the corresponding client-side type might be CartResponse:

export type CartResponse = AsyncData<
  {
    cart: Cart;
  },
  H3Error
>;

For a mutation that removes items from the cart, the corresponding type might be CartRemoveItemResponse:

export type CartRemoveItemResponse = AsyncData<
  {
    cartRemoveMultipleItems: Cart;
  },
  H3Error
>;

Creating Queries

Queries are created in TypeScript files located in the /server/queries directory. Each query should have its own file, named according to the query name.

Simple Query Example

Below is an example of how a query like LoadCartQuery should be structured in the loadCartQuery.ts file:

import { gql } from '@apollo/client/core';

export default gql`
  query {
    cart {
      order {
        id
        name
      }
    }
  }
`;

Creating Mutations

Mutations are created in TypeScript files located in the /server/mutations directory. Each mutation should have its own file, named according to the mutation name. Below is an example of how a mutation like CartRemoveItem should be structured in the cartRemoveItem.ts file:

import gql from 'graphql-tag';
import orderFragment from '../fragments/orderFragment';

export default gql`
  mutation ($lineIds: [Int]!) {
    cartRemoveMultipleItems(lineIds: $lineIds) {
      order {
        id
        name
      }
    }
  }
`;

Registering Queries and Mutations

All queries must be registered in the /server/queries/index.ts file.

import LoadCartQuery from './LoadCartQuery';

enum QueryName {
  LoadCartQuery = 'LoadCartQuery',
}

const Queries: Record<QueryName, DocumentNode> = {
  LoadCartQuery,
};

export { Queries, QueryName };

All mutations must be registered in the /server/mutations/index.ts file.

import CartRemoveItem from './CartRemoveItem';

enum MutationName {
  CartRemoveItem = 'CartRemoveItem',
}

const Mutations: Record<MutationName, DocumentNode> = {
  CartRemoveItem,
};

export { Mutations, MutationName };

Code Implementation

Query without parameters: When the API does not require parameters, the query can be simple and straightforward.

const cart = useState<Cart>('cart', () => ({} as Cart));
const { data } = await $sdk().odoo.query<null, CartResponse>({
  queryName: QueryName.LoadCartQuery,
});
cart.value = data.value.cart;

Query with parameters: When the operation requires parameters, you must pass them in the mutation.

const cart = useState<Cart>('cart', () => ({} as Cart));

const { data, error } = await $sdk().odoo.mutation<
  MutationCartRemoveMultipleItemsArgs,
  CartRemoveItemResponse
>({ mutationName: MutationName.CartRemoveItem }, params);

cart.value = data.value.cartRemoveMultipleItems;