Interfacing with the External API

General

External API Docs

We have migrated to a system where the website queries an external API that sits between the database and all of our endpoint services to exchange data with the database or discord. The main way this is done is through use of the onFetch hook within pages and components. onFetch provides a number of methods that correspond to the various HTTP request methods. Using these wrapper methods to interact with onFetch is standard practice. Note that the onFetch hook handles authorization with the API automatically.

onGet

async function onGet<R>(url: string, schema: ZodObject | ZodArray, query?: [string, string][], signal?: AbortSignal)

• R - a generic type parameter that is used to cast the parsed payload of the response (must be accompanied with a corresponding zodSchema argument)
• url - a string parameter containing the url path to the target API endpoint
• schema - a zodSchema object that is used to parse the payload object into a typed format (must be accompanied by a corresponding generic type argument)
• query - and optional parameter representing the key, value pairs of query arguments in the form of an array of [string, string] tuples
• signal - an optional parameter that I frankly have no clue what it does

onGet Example

const { onGet } = useFetch()
const [fooList, setFooList] = useState<IFoo[]>()

useEffect(() => {
   onGet<IFoo[]>('/foos', z.array(zFoo))
   .then((res) => {
      setFooList(res)
   })
   .catch((err) => {
      console.error(err)
   })
}, [])

onPut

async function onPut(url: string, body: object | null, signal?: AbortSignal)

• url - a string parameter containing the url path to the target API endpoint
• body - a nullable object parameter that allows you to pass through a payload object to the fetch request
• signal - an optional parameter that I frankly have no clue what it does

onPut Example

const { onPut } = useFetch()

const addBarToFoo = async (fooId: number, barId: number, options?: { barTags?: string[] }) => {
   await onPut(`/foos/${fooId}/bars/${barId}`, options ?? null) 
}

onPost

async function onPost<R = void>(url: string, body: object | null, schema: ZodObject | ZodArray | null, signal?: AbortSignal)

• R - a generic type parameter used to cast the return type (defaults to void; must be accompanied by a corresponding zodSchema argument if not void)
• url - a string parameter containing the url path to the target API endpoint
• body - a nullable object parameter that allows you to pass through a payload object to the fetch request
• schema - a zodSchema object that is used to parse the payload object into a typed format (must be accompanied by a corresponding generic type argument if not null)
• signal - an optional parameter that I frankly have no clue what it does

onPost Example

const { onPost } = useFetch()

const handleCallback = async (fooId: number, payload: object) => {
   return await onPost<IFoo>(`/foos/${fooId}/attendance`, payload, zFoo)
}

onPatch

async function onPatch<R = void>(url: string, body: object | null, schema: ZodObject | ZodArray | null, signal?: AbortSignal)

• R - a generic type parameter used to cast the return type (defaults to void; must be accompanied by a corresponding zodSchema argument if not void)
• url - a string parameter containing the url path to the target API endpoint
• body - a nullable object parameter that allows you to pass through a payload object to the fetch request
• schema - a zodSchema object that is used to parse the payload object into a typed format (must be accompanied by a corresponding generic type argument if not null)
• signal - an optional parameter that I frankly have no clue what it does

onPatch Example

const { onPatch } = useFetch()

const handleOnSubmit = async (fooId: number, payload: object) => {
   return await onPatch<IFoo>(`/foos/${fooId}`, payload, zFoo)
{

onDelete

async function onDelete(url: string, signal?: AbortSignal)

• url - a string parameter containing the url path to the target API endpoint
• signal - an optional parameter that I frankly have no clue what it does

onDelete Example

const { onDelete } = useFetch()

const handleOnDelete = async (fooId: number) => {
   await onDelete(`/foos/${fooId}`)
}