Build Delivery APIs

In FoxNose CMS, you have the flexibility to create multiple Delivery APIs within a single environment. Each API represents a specific set of connected folders from which you can distribute data. This allows for granular control over which content is exposed and how it's organized for consumption.

Key Concepts

Each Delivery API has a unique prefix that serves as the starting point for its URLs structure. This helps in differentiating between multiple APIs within the same environment.

Example 1

https://7c9h4pwu.fxns.io/my_api_prefix/.../

Example 2

https://7c9h4pwu.fxns.io/another_prefix/.../

After creating an API, you connect folders to it. Only the data from these connected folders will be accessible through the Delivery API. You can connect multiple folders to the same API, each with its own configuration.

URL Structure

The structure of the API mirrors the structure of the connected folders. This means the endpoints are organized based on how folders and subfolders are arranged. Endpoints parts are generated using the api_key_plural property of the folders. This ensures meaningful and consistent URL paths.

...fxns.io/my_public_api/manufacturers/:manufacturer_key/products/:product_key/.../

Inheritance and strict_reference

When you connect a folder that has strict_reference enabled to your Delivery API, FoxNose CMS automatically includes certain ancestor folders in the API's URL structure. Here's how it works:

1. Automatic Inclusion of Ancestor Folders

• Chain of strict_reference Folders: Only ancestor folders that have strict_reference enabled are automatically included in the API's URL structure.
• Stops at non-strict_reference Folders: If an ancestor folder does not have strict_reference enabled, the automatic inclusion stops there. Any higher-level ancestors without strict_reference are skipped in the URL structure.

2. Role of Included Ancestor Folders

• URL Structure Only: These ancestor folders are added to the API with allowed_methods set to an empty list []. This means they become part of the URL path but do not allow direct access to their content.
• No Direct Data Access: Since allowed_methods is empty, clients cannot perform actions like retrieving lists or individual items from these folders through the API.

3. Explicit Connection for Data Access

• Connect to Serve Content: If you want the ancestor folders to serve content (e.g., allow get_many or get_one), you need to explicitly connect them to the API and specify the desired allowed_methods using the Update Connected Folder endpoint.

Why This Matters

• Accurate URL Paths: Including ancestor folders with strict_reference in the URL ensures that your API endpoints accurately reflect the content hierarchy. This is important for correctly identifying and accessing nested records.
• Controlled Access: By not automatically enabling data access to ancestor folders, you maintain control over which folders expose their content via the API.

Example Setup

Consider the following folder structure:

📁 Blog (api_key_plural: articles, strict_reference: false)
└── 📁 Articles (api_key_plural: articles, strict_reference: false)
    └── 📁 Categories (api_key_plural: categories, strict_reference: true)
        ├── 📁 Tech (api_key_plural: tech, strict_reference: true)
        │    └── 📄 Document 1
        └── 📁 Lifestyle (api_key_plural: lifestyle, strict_reference: true)
             └── 📄 Document 2

Let’s say only Articles and Tech folders are connected to the Delivery API with the strict_reference setting enabled for Tech. This means that Categories will also be part of the URL structure but will not serve content unless explicitly connected.

In this example:

If Tech is connected to the API with strict_reference, only its immediate ancestor folders (Categories) with strict_reference are automatically added to the URL structure.

URL to get a list of articles under the Tech category:

/api_prefix/categories/:category_key/tech/

URL to retrieve a specific article in Tech:

/api_prefix/categories/:category_key/tech/:article_key/

The Blog and Articles folders are not added to the URL structure because they lack strict_reference. Even though they are part of the hierarchy, they do not appear in the API structure, keeping the URL concise and relevant.

Attempting to access /api_prefix/categories/ directly will result in a “Method Not Allowed” error, as Categories only serves as a structural element in the URL path without exposing its content directly.

Permissions

When connecting a folder to an API, you can specify an array of actions (permissions) that are allowed for that folder, providing control over what operations can be performed on the data.

Delivery API Model

Properties

Create Delivery API

curl https://api.foxnose.net/v1/7c9h4pwu/api/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"name": "My API",
"description": "An example API",
"prefix": "my_api"
}'

{
    "key": "6n39zhwb",
    "name": "My API",
    "environment": "7c9h4pwu",
    "description": "An example API",
    "created_at": "2024-09-21T16:45:20.516605-05:00",
    "prefix": "my_api"
}

List Delivery APIs

curl https://api.foxnose.net/v1/7c9h4pwu/api/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

[
{
    "key": "6n39zhwb",
    "name": "My API",
    "environment": "7c9h4pwu",
    "description": "My first API",
    "created_at": "2024-09-21T16:45:20.516605-05:00",
    "prefix": "my_api"
},
{
    "key": "7b8gzkla",
    "name": "Analytics API",
    "environment": "7c9h4pwu",
    "description": "API for analytics data",
    "created_at": "2024-09-22T11:45:20.516605-05:00",
    "prefix": "analytics"
}
]

Retrieve Delivery API

curl https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "key": "6n39zhwb",
    "name": "My API",
    "environment": "7c9h4pwu",
    "description": "My first API",
    "created_at": "2024-09-21T16:45:20.516605-05:00",
    "prefix": "my_api"
}

Update Delivery API

curl https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"name": "Updated API",
"description": "Updated description",
"prefix": "updated_prefix"
}'

{
    "key": "6n39zhwb",
    "name": "Updated API",
    "environment": "7c9h4pwu",
    "description": "Updated description",
    "created_at": "2024-09-21T16:45:20.516605-05:00",
    "prefix": "updated_prefix"
}

Delete Delivery API

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

Folder Connection Model

When connecting folders to a Delivery API in FoxNose CMS, you define specific settings that control how data from those folders is accessed and presented through the API. This model outlines the properties used to configure folder connections to an API.

Properties

Connect Folder to API

curl -X POST https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/folders/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"folder": "5fnvjnk6",
"allowed_methods": ["get_many", "get_one"],
"return_fields": ["title", "content"],
"filters": {
"foo": true,
"bar__eq": 42
}
}'

{
    "folder": "5fnvjnk6",
    "api": "6n39zhwb",
    "allowed_methods": ["get_many", "get_one"],
    "return_fields": ["title", "content"],
    "filters": {
    "foo": true,
    "bar__eq": 42
}
}

List Connected Folders

curl https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/folders/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "count": 2,
    "next": null,
    "previous": null,
    "results":
    [
{
    "folder": "5fnvjnk6",
    "api": "6n39zhwb",
    "allowed_methods": ["get_many", "get_one"],
    "return_fields": ["title", "content"],
    "filters": {
    "published_at__gte": "2024-09-21T16:45:20.516605-05:00"
}
},
{
    "folder": "8v4k2h9m",
    "api": "6n39zhwb",
    "allowed_methods": ["get_many"],
    "return_fields": ["name", "description"],
    "filters": {
    "status__eq": "active"
}
}
    ]
}

Retrieve Connected Folder

curl https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/folders/5fnvjnk6/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"

{
    "folder": "5fnvjnk6",
    "api": "6n39zhwb",
    "allowed_methods": ["get_many", "get_one"],
    "return_fields": ["title", "content"],
    "filters": {
    "published_at__gte": "2024-09-21T16:45:20.516605-05:00"
}
}

Update Connected Folder

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/folders/5fnvjnk6/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
"allowed_methods": ["get_many"],
"return_fields": ["title", "content", "date"],
"filters": {
"published": true
}
}'

{
    "folder": "5fnvjnk6",
    "api": "6n39zhwb",
    "allowed_methods": ["get_many"],
    "return_fields": ["title", "content", "date"],
    "filters": {
    "published": true
}
}

Disconnect Folder

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/api/6n39zhwb/folders/5fnvjnk6/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json"