API Overview
Relevant source files
The following files were used as context for generating this wiki page:
The CertDb project exposes a set of static JSON API endpoints to provide data about cybersecurity certifications. These endpoints are generated at build time by Astro, ensuring high performance and availability of the certification data for the frontend application. The API is designed to be consumed by client-side components to display, filter, and search the certification database.
The core of the API revolves around providing certification metadata, either as a complete dataset or filtered by specific career paths. To optimize client-side search performance, the API also generates pre-computed search indexes using Fuse.js. This architecture allows for a fast, interactive user experience without requiring a live server-side backend for data queries.
Data Architecture
The data for the API is sourced from Markdown (.md/.mdx) files located in src/content/certifications. Astro's content collections feature is used to parse these files and make them available for the API endpoints to process and serve as JSON.
Data Flow
The following diagram illustrates the data flow from the source content files to the final JSON API endpoints.
This diagram shows how markdown content is processed by the getCertificationMetadata function, which then feeds into the various data and search index API endpoints.
Sources: src/pages/database/data.json.ts:10-29, src/pages/database/data-index.json.ts:9-13, src/content.config.ts:5-19
Core Data Models
Certification Metadata
The primary data object returned by the API is CertificationMetadata. It contains all relevant details for a single certification.
| Field | Type | Description |
|---|---|---|
image | string | The source path to the certification's image. |
provider | string | The name of the organization providing the certification. |
title | string | The full title of the certification. |
acronym | string | The acronym for the certification. |
last_updated_at | Date | The date the certification information was last updated. |
reference | string | A URL to the official certification page. |
aliases | string[] | (Optional) Alternative names or acronyms for the certification. |
career_paths | string[] | An array of associated career paths. |
price | string | The price of the certification. |
currency | string | The currency for the price. |
slug | string | A unique, URL-friendly identifier for the certification. |
Sources: src/types/certification-metadata.ts:1-14, src/content.config.ts:7-18
Career Paths
Career paths are predefined categories used to group certifications. The list of available career paths is statically defined.
Sources: src/lib/career-paths.ts:18-30
API Endpoints
The application generates several JSON endpoints at build time. These are used by the frontend to fetch data for display and searching.
| Endpoint | Method | Description | Source File |
|---|---|---|---|
/database/data.json | GET | Returns a collection of all certification metadata. | src/pages/database/data.json.ts |
/database/data-index.json | GET | Returns a pre-computed Fuse.js index for all certifications. | src/pages/database/data-index.json.ts |
/career-paths/{path}/data.json | GET | Returns certifications filtered by a specific career path. | src/pages/career-paths/[path]/data.json.ts |
/career-paths/{path}/data-index.json | GET | Returns a Fuse.js index for certifications within a specific career path. | src/pages/career-paths/[path]/data-index.json.ts |
GET /database/data.json
This endpoint returns a JSON array containing CertificationMetadata for every certification in the system, excluding those marked as drafts.
The data is generated by the getCertificationMetadata function, which retrieves all entries from the certifications content collection, filters out drafts, and maps the data to the CertificationMetadata structure. This includes transforming the id into a provider and slug.
// src/pages/database/data.json.ts:10-29
export async function getCertificationMetadata(filter?: (entry: CollectionEntry<"certifications">) => boolean): Promise<CertificationMetadataCollection> {
const certifications = await getCollection(
"certifications",
(entry) => {
const reponse = !entry.data.draft;
if (filter) {
return reponse && filter(entry);
}
return reponse;
},
);
return certifications.map(
(certification) =>
({
...omit(certification.data, [ "draft" ]),
image: certification.data.image.src,
provider: title(certification.id.split("/")[0]),
slug: certification.id,
}) as CertificationMetadata,
) as CertificationMetadataCollection;
}
Sources: src/pages/database/data.json.ts:10-34
GET /database/data-index.json
To facilitate fast, client-side searching, this endpoint provides a pre-computed search index generated by Fuse.js. The ReactiveDatatable component fetches this index along with the full dataset to perform searches without needing to build the index on the client.
// src/pages/database/data-index.json.ts:9-13
export const GET: APIRoute = async () => {
const index = Fuse.createIndex(
FuseConfig.keys!,
await getCertificationMetadata(),
);
return Response.json(index.toJSON());
};
Sources: src/pages/database/data-index.json.ts:9-15
GET /career-paths/{path}/data.json
This is a dynamic route that generates a separate JSON file for each career path. The {path} parameter is a kebab-cased version of the career path name (e.g., blue-team-specialist).
The endpoint uses a lookup table to map the URL path back to the original career path name and then filters the certifications accordingly using the getCertificationMetadata function.
// src/pages/career-paths/[path]/data.json.ts:41-46
export const GET: APIRoute = async ({ params }) => {
const lookup_table = makeCareerPathLookupTable();
return Response.json(await getCertificationMetadata(
(entry) => entry.data.career_paths.includes(lookup_table[params.path as string]),
));
};
Sources: src/pages/career-paths/[path]/data.json.ts:12-46
GET /career-paths/{path}/data-index.json
Similar to the main data index, this dynamic route provides a pre-computed Fuse.js index for the certifications belonging to a specific career path. This allows for efficient searching within a filtered subset of data.
Sources: src/pages/career-paths/[path]/data-index.json.ts:15-22
Client-Side Consumption
The ReactiveDatatable.tsx component demonstrates how these API endpoints are consumed on the client. On component mount, it fetches both /data.json and /data-index.json in parallel. The data is stored, and the pre-computed index is loaded into a new Fuse.js instance, enabling immediate search functionality.
The following sequence diagram shows the interaction between the client and the API.
This diagram illustrates the parallel fetching of data and the search index, followed by a client-side search operation.
Sources: src/components/astro/database/reactive-datatable.tsx:162-212
Summary
The CertDb API is a statically generated set of JSON files that serves certification data to the frontend. It is designed for performance by providing pre-built datasets and search indexes, which enables a fast and responsive user experience for searching and browsing certifications. The use of Astro's content collections and dynamic routing allows for a maintainable and scalable system where new certifications can be added simply by creating new Markdown files.