Last published: 2025-11-02
This guide is intended to provide an overview of the conventions and design principles used by the Baack APIs. The majority of this guide is specific to the /n/ (native) API as other APIs may follow external conventions.
What is a REST-ful API? REST stands for Representation State Transfer. The concept being that the representation of a resource is described in the document addressed by a URL. We have endeavoured to follow the principles of REST to their logical limit so you will see conventions below like the use of state attributes as part of the representation of an resource. This is distinct from Remote Procedure Call (RPC) APIs which encode a specific function interface.
Another aspect of REST is that the returned documents include hyperlinks for associated items. Any addressable object will include a url attribute which can be used to interact with that representation. The URLs included in responses are provided for convenience and are ignored on writes. For simplicity representations can be passed from one endpoint to another and the URLs will be ignored.
Baack has been built as an 'API first' product where the first interface offered for a concept is it's native API rather than a user interface. Baack is intended to be used as a headless back-end for developers and companies building digital products so our entire product surface is available via our APIs. Our site is an example of this, it is built on our own content APIs for delivery of the content you are reading now.
Our APIs are intended to be intuitive and do exactly what you would expect without any surprises. API endpoints provide helpful error messages and feedback when there is an issue with the provided representation. This is intended to allow developers to start small and quickly receive meaningful feedback based on experience.
Though the APIs support multiple different business functions like Customer Relationship Management and Identity Management, these concepts leverage the content approach used for delivery of content. The core of our content approach is a content entity which is analogous to a page of content. Multiple other concepts have associated content like company and membership group. This allows you to easily associate content with different concepts.
JavaScript Object Notation (JSON) has become universally accepted as the most common way of encoding representations of concepts so our APIs all use JSON be default. JSON is also the normal format for web applications used by web app frameworks like React, Angular, Vue etc.
Further encoding formats will be supported in future, if you have specific requirements please contact us.
As a small optimisation our endpoints will omit attributes that have no value as a key without a value generally signifies the absence of a value so these concepts are conflated to minimise the representation size.
Hyper Text Transfer Protocol (HTTP) is used for transfer of representations for the standard Create, Read, Update, Delete approach. There is a little variation and ambiguity around the exact mapping of CRUD concepts to HTTP verbs so we have used a simple consistent scheme:
HTTP POST and IDs are allocated by the request handler with the created ID being returned in the response representation. POST is always used for creating a representation.HTTP GET which maps nicely to the concept of reading a known resource.HTTP PUT which maps to SQL style UPDATE as endpoints may modify or replace known resources depending on the logic of the specific endpoint. PUT is also mentioned as a potential Create verb in some platforms however this creates ambiguity around CRUD intentions depending on whether a specific resource is being modified so we have separated these intentions out to avoid ambiguity.HTTP DELETE which provides a consistent mapping for the intention. Note that when a resource is deleted this may also trigger other resources to be deleted if they are chained or dependent e.g. if you remove a content entity it's content items will also be deleted.Our APIs use standard authentication mechanisms intended to be familiar to developers with the minimal amount of cognitive load to understand how they are used. Authorisation on the platform uses our own Role Based Access Control system to provide access to resources. Resources are typically associated with an owning company for which API access is granted using either a Authorization: Bearer token or a managed session (OAuth) for access to data.