Portfolio CMS API

A Portfolio CMS API is not just a random collection of create, read, update, and delete routes. Its purpose is to power a real portfolio website or developer blog where content has meaning: projects can be featured, posts can be drafts or published, images belong to specific resources, tags help filtering, and public pages should only expose content that is ready to be shown.

A common mistake is creating generic endpoints such as /items or /data without modeling the actual content types. This makes the frontend harder to build because every page has to guess what the data means. A better API should clearly separate resources such as projects, blog posts, skills, experience, achievements, media files, and profile information.

For frontend developers learning Node.js, this is one of the most important lessons. A backend should give the frontend predictable, meaningful data. If the portfolio homepage needs featured projects and recent posts, the API should make that data easy to request and easy to render.

Problematic generic model:

          const itemSchema = new mongoose.Schema({
            title: String,
            content: String,
            type: String,
            image: String
          });

This schema is too vague. The backend cannot clearly enforce project-specific fields, blog-specific fields, publication status, or SEO metadata.

Better portfolio content models:

          type ProjectStatus = "draft" | "published" | "archived";

          type PortfolioProject = {
            id: string;
            title: string;
            slug: string;
            summary: string;
            description: string;
            technologies: string[];
            liveUrl?: string;
            repositoryUrl?: string;
            coverImageId?: string;
            featured: boolean;
            status: ProjectStatus;
            createdAt: string;
            updatedAt: string;
            publishedAt?: string;
          };

          type BlogPost = {
            id: string;
            title: string;
            slug: string;
            excerpt: string;
            content: string;
            tags: string[];
            coverImageId?: string;
            status: "draft" | "published";
            seoTitle?: string;
            seoDescription?: string;
            createdAt: string;
            updatedAt: string;
            publishedAt?: string;
          };

Frontend-oriented API routes:

          GET    /api/public/profile
          GET    /api/public/projects
          GET    /api/public/projects/featured
          GET    /api/public/projects/:slug
          GET    /api/public/posts
          GET    /api/public/posts/:slug

          POST   /api/admin/projects
          PATCH  /api/admin/projects/:projectId
          DELETE /api/admin/projects/:projectId

          POST   /api/admin/posts
          PATCH  /api/admin/posts/:postId
          DELETE /api/admin/posts/:postId

Pay attention to: Model portfolio content as real content types, not generic records. Projects, posts, media, skills, and profile sections need clear fields and clear public/admin routes.

A portfolio website has two very different audiences. Public visitors should be able to read published projects, blog posts, profile information, and skills without logging in. The portfolio owner should be able to create, edit, delete, upload, publish, and archive content through protected admin endpoints. A common mistake is mixing these two concerns into the same routes.

If the same endpoint returns drafts to the public frontend and also supports editing content, the API becomes risky. Draft posts may appear before they are ready. Admin-only fields may leak into the public site. Frontend code may need confusing checks such as “hide this if not published.” The backend should enforce the separation.

A cleaner approach is to create public routes for published content and admin routes for authenticated content management. Public routes should never require a token and should only return safe fields. Admin routes should require JWT authentication and should return additional management fields such as status, internal notes, draft content, and edit metadata.

Problematic route:

          router.get("/projects", async (request, response) => {
            const projects = await Project.find();

            response.json(projects);
          });

          router.post("/projects", async (request, response) => {
            const project = await Project.create(request.body);

            response.status(201).json(project);
          });

The public route returns everything, including drafts and admin-only fields. The create route is also unprotected.

Better public route:

          router.get("/public/projects", async (request, response, next) => {
            try {
              const projects = await projectService.getPublishedProjects({
                featured: request.query.featured === "true",
                technology: request.query.technology?.toString(),
                page: Number(request.query.page || 1)
              });

              response.json({
                data: projects.items,
                meta: projects.meta
              });
            } catch (error) {
              next(error);
            }
          });

Better admin route:

          router.post(
            "/admin/projects",
            requireAuth,
            validateBody(createProjectSchema),
            async (request, response, next) => {
              try {
                const project = await projectService.createProject({
                  input: request.body,
                  authorId: request.user.id
                });

                response.status(201).json({
                  data: project
                });
              } catch (error) {
                next(error);
              }
            }
          );

Public projection example:

          function toPublicProjectDto(project: PortfolioProject) {
            return {
              id: project.id,
              title: project.title,
              slug: project.slug,
              summary: project.summary,
              technologies: project.technologies,
              liveUrl: project.liveUrl,
              repositoryUrl: project.repositoryUrl,
              coverImageUrl: project.coverImageUrl,
              publishedAt: project.publishedAt
            };
          }

Pay attention to: Separate public reading from admin editing. Public endpoints should expose only published content, while admin endpoints require authentication and return management fields.

Portfolio and blog content usually needs readable URLs. A project page such as /projects/ecommerce-dashboard is much better than /projects/65f89a.... A common mistake is building the CMS around database IDs only and adding slugs later. This often creates duplicate slug bugs, broken links, and inconsistent frontend routing.

Slugs should be treated as part of the content model from the beginning. They should be generated from titles, checked for uniqueness, and updated carefully. Published content also needs status fields, timestamps, and SEO metadata. Without these fields, the frontend cannot reliably build public routes, sitemap entries, article previews, or social sharing cards.

This does not mean overbuilding a full enterprise CMS. It means giving each content item the basic metadata needed for a real website: slug, status, title, excerpt, SEO description, created date, updated date, and published date.

Problematic blog model:

          const postSchema = new mongoose.Schema({
            title: String,
            content: String
          });

This is too limited for a CMS. The frontend cannot build stable routes, draft previews, SEO metadata, or filtered public lists.

Better blog schema:

          const blogPostSchema = new mongoose.Schema(
            {
              title: {
                type: String,
                required: true,
                trim: true
              },
              slug: {
                type: String,
                required: true,
                unique: true,
                index: true
              },
              excerpt: {
                type: String,
                required: true
              },
              content: {
                type: String,
                required: true
              },
              tags: {
                type: [String],
                default: []
              },
              status: {
                type: String,
                enum: ["draft", "published", "archived"],
                default: "draft"
              },
              seoTitle: String,
              seoDescription: String,
              publishedAt: Date
            },
            {
              timestamps: true
            }
          );

Slug helper:

          function createSlug(value: string): string {
            return value
              .toLowerCase()
              .trim()
              .replace(/[^a-z0-9]+/g, "-")
              .replace(/^-+|-+$/g, "");
          }

          async function createUniqueSlug(title: string): Promise<string> {
            const baseSlug = createSlug(title);
            let slug = baseSlug;
            let counter = 1;

            while (await BlogPost.exists({ slug })) {
              slug = `${baseSlug}-${counter}`;
              counter += 1;
            }

            return slug;
          }

Publishing logic:

          async function publishPost(postId: string) {
            const post = await BlogPost.findById(postId);

            if (!post) {
              throw new NotFoundError("Post not found.");
            }

            post.status = "published";
            post.publishedAt = post.publishedAt || new Date();

            await post.save();

            return post;
          }

Pay attention to: Slugs, status, timestamps, and SEO metadata are core CMS fields. Add them early so the frontend can build stable pages and previews.

Portfolio projects and blog posts usually need images: project screenshots, cover images, avatars, logos, and article thumbnails. A common mistake is uploading a file and saving only a raw path string inside the project or post. This works for a small demo, but it becomes limiting when you need alt text, file size validation, image replacement, deletion, or multiple image sizes.

A better CMS API treats uploaded media as its own resource. The file upload endpoint should validate file type and size, store the file safely, and return a structured media object. Projects and posts can then reference media by ID or by a normalized media object. This makes the frontend easier to build because image URLs, alt text, width, height, and metadata are available in a predictable format.

This also prepares the project for future storage changes. The first version may use local uploads. Later, you may move to Cloudinary, S3, Firebase Storage, or another service. If the frontend already consumes a stable media DTO, the storage backend can change without rewriting every card component.

Problematic upload route:

          router.post("/upload", upload.single("image"), (request, response) => {
            response.json({
              image: request.file.path
            });
          });

This response does not tell the frontend what the file represents, whether it is safe, or how it should be displayed.

Better media model:

          type MediaAsset = {
            id: string;
            url: string;
            fileName: string;
            mimeType: string;
            sizeBytes: number;
            width?: number;
            height?: number;
            altText: string;
            uploadedById: string;
            createdAt: string;
          };

Upload validation:

          const upload = multer({
            storage: multer.memoryStorage(),
            limits: {
              fileSize: 3 * 1024 * 1024
            },
            fileFilter: (request, file, callback) => {
              const allowedTypes = ["image/jpeg", "image/png", "image/webp"];

              if (!allowedTypes.includes(file.mimetype)) {
                callback(new ValidationError("Only JPG, PNG, and WebP images are allowed."));
                return;
              }

              callback(null, true);
            }
          });

Media upload endpoint:

          router.post(
            "/admin/media",
            requireAuth,
            upload.single("file"),
            async (request, response, next) => {
              try {
                if (!request.file) {
                  throw new ValidationError("File is required.");
                }

                const media = await mediaService.createMediaAsset({
                  file: request.file,
                  altText: request.body.altText,
                  uploadedById: request.user.id
                });

                response.status(201).json({
                  data: media
                });
              } catch (error) {
                next(error);
              }
            }
          );

Frontend-friendly media response:

          {
            "data": {
              "id": "media_1",
              "url": "https://cdn.example.com/uploads/project-dashboard.webp",
              "fileName": "project-dashboard.webp",
              "mimeType": "image/webp",
              "sizeBytes": 184233,
              "altText": "Dashboard project screenshot",
              "createdAt": "2026-06-19T12:00:00.000Z"
            }
          }

Pay attention to: Treat images as CMS media assets, not only file paths. Validate uploads and return structured metadata that the frontend can safely use.

Frontend developers need predictable API contracts. A common backend mistake is returning different shapes from different endpoints. One route returns a project directly, another returns { result: project }, another returns { success: true, data: project }, and validation errors vary from route to route. This makes frontend integration unnecessarily painful.

A Portfolio CMS API should use consistent response shapes. Successful responses can use { data }. Lists can use { data, meta }. Errors can use a standard { error } object with code, message, status, and optional field details. This allows frontend code to implement reusable API clients, form error mapping, toast messages, and loading/error states.

Validation is especially important for CMS forms. The admin panel needs to show useful messages when a title is missing, a slug is duplicated, an image is too large, or a URL is invalid. If the backend only returns “Bad request,” the frontend cannot create a good editing experience.

Problematic responses:

          response.json(project);

          response.json({
            success: true,
            result: posts
          });

          response.status(400).send("Invalid data");

These responses force the frontend to write custom parsing logic for every endpoint.

Better success response:

          {
            "data": {
              "id": "project_1",
              "title": "Portfolio CMS API",
              "slug": "portfolio-cms-api",
              "status": "published"
            }
          }

Better paginated response:

          {
            "data": [
              {
                "id": "post_1",
                "title": "How I Built My Portfolio CMS",
                "slug": "how-i-built-my-portfolio-cms"
              }
            ],
            "meta": {
              "page": 1,
              "limit": 10,
              "totalItems": 42,
              "totalPages": 5
            }
          }

Better validation error:

          {
            "error": {
              "code": "VALIDATION_ERROR",
              "message": "Request body contains invalid fields.",
              "status": 400,
              "details": {
                "title": ["Title is required."],
                "slug": ["Slug is already used."],
                "liveUrl": ["Live URL must be a valid URL."]
              }
            }
          }

Centralized error middleware:

          function errorHandler(error, request, response, next) {
            if (error instanceof ValidationError) {
              return response.status(400).json({
                error: {
                  code: "VALIDATION_ERROR",
                  message: "Request body contains invalid fields.",
                  status: 400,
                  details: error.details
                }
              });
            }

            if (error instanceof NotFoundError) {
              return response.status(404).json({
                error: {
                  code: "NOT_FOUND",
                  message: error.message,
                  status: 404
                }
              });
            }

            return response.status(500).json({
              error: {
                code: "INTERNAL_SERVER_ERROR",
                message: "Something went wrong.",
                status: 500
              }
            });
          }

Pay attention to: Stable response contracts make frontend integration much easier. Use consistent success, list, pagination, and error formats across the entire API.

A portfolio CMS may start with only three projects and two posts, but the API should still be designed as if content can grow. A common mistake is returning every record from every list endpoint. This may seem fine in development, but it becomes inefficient when the portfolio has many posts, tags, screenshots, drafts, archived projects, or admin-only records.

Public frontend pages need fast, focused endpoints. The homepage may need only featured projects and latest posts. The blog page may need pagination, tag filtering, and search. The admin panel may need draft and archived content. These are different needs, so the API should support query parameters and metadata instead of returning one oversized list.

This also helps SEO and performance. Public routes should be cache-friendly where possible. Admin routes should remain protected and dynamic. Frontend developers benefit from this because pages load faster and state management becomes simpler.

Problematic list route:

          router.get("/posts", async (request, response) => {
            const posts = await BlogPost.find();

            response.json({
              data: posts
            });
          });

This returns drafts, archived posts, and every record at once. It does not support public filtering or pagination.

Better query schema:

          type PublicPostQuery = {
            page: number;
            limit: number;
            tag?: string;
            search?: string;
          };

          function parsePublicPostQuery(query: Record<string, unknown>): PublicPostQuery {
            return {
              page: Math.max(Number(query.page || 1), 1),
              limit: Math.min(Math.max(Number(query.limit || 10), 1), 50),
              tag: typeof query.tag === "string" ? query.tag : undefined,
              search: typeof query.search === "string" ? query.search : undefined
            };
          }

Paginated public route:

          router.get("/public/posts", async (request, response, next) => {
            try {
              const query = parsePublicPostQuery(request.query);

              const result = await postService.getPublishedPosts(query);

              response.setHeader("Cache-Control", "public, max-age=60");

              response.json({
                data: result.items,
                meta: {
                  page: query.page,
                  limit: query.limit,
                  totalItems: result.totalItems,
                  totalPages: Math.ceil(result.totalItems / query.limit)
                }
              });
            } catch (error) {
              next(error);
            }
          });

Homepage endpoint example:

          router.get("/public/homepage", async (request, response, next) => {
            try {
              const homepage = await contentService.getHomepageContent();

              response.json({
                data: {
                  profile: homepage.profile,
                  featuredProjects: homepage.featuredProjects,
                  latestPosts: homepage.latestPosts
                }
              });
            } catch (error) {
              next(error);
            }
          });

Pay attention to: Add filtering, pagination, and focused public endpoints early. Frontend pages should request exactly the content they need, not the entire CMS database.