Public APIs

Complete API documentation for public-facing applications (mobile apps, websites, etc.). These endpoints are publicly accessible and do not require authentication.

Base URL: https://ycwadelaide.adenmgb.com
Development: https://dev.ycwadelaide.adenmgb.com

Overview

These endpoints provide:

• Read-only access to published content
• Public submissions (contact forms, newsletter subscriptions, etc.)
• SEO and feed endpoints (RSS, sitemap)

No Authentication Required - All public endpoints are accessible without authentication.

Content APIs

GET /api/actions

Retrieve all published YCW actions.

Query Parameters:

• tag (optional) - Filter by tag slug

Response:

[
  {
    "id": 1,
    "title": "SOL Music Events",
    "slug": "sol-music-events",
    "description": "Join us for music events",
    "content": "<p>Full HTML content...</p>",
    "icon": "MusicalNoteIcon",
    "gradientClass": "from-purple-500 to-pink-500",
    "coverImageUrl": "/api/images/cover.jpg",
    "tags": [{"id": 1, "name": "Events", "slug": "events"}]
  }
]

Notes:

• Only returns published actions
• Results ordered by displayOrder ASC
• Includes tags and author information

GET /api/actions/:slug

Get a single published action by slug.

Response: Full action details including content and tags.

GET /api/news

Retrieve all published news articles.

Query Parameters:

• tag (optional) - Filter by tag slug
• limit (optional) - Limit number of results (default: 50)
• offset (optional) - Pagination offset

Response:

[
  {
    "id": 1,
    "title": "YCW Adelaide News Update",
    "slug": "ycw-adelaide-news-update",
    "description": "Latest news",
    "content": "<p>Full article...</p>",
    "category": "Events",
    "imageUrl": "/api/images/news-cover.jpg",
    "tags": [{"id": 1, "name": "Events", "slug": "events"}],
    "publishedAt": "2024-12-01T10:00:00.000Z"
  }
]

Notes:

• Only returns published articles
• Results ordered by publishedAt DESC
• Limited to 50 most recent by default

GET /api/news/:slug

Get a single published news article by slug.

Response: Full article details including content and tags.

GET /api/events

Retrieve all published events.

Query Parameters:

• tag (optional) - Filter by tag slug
• upcoming (optional) - If true, only returns future events

Response:

[
  {
    "id": 1,
    "title": "YCW Adelaide Annual Meeting",
    "slug": "ycw-adelaide-annual-meeting",
    "description": "Join us for our annual meeting",
    "startDate": "2024-12-20T18:00:00.000Z",
    "endDate": "2024-12-20T20:00:00.000Z",
    "location": "YCW Adelaide Office",
    "imageUrl": "/api/images/event-cover.jpg",
    "link": "https://example.com/register",
    "tags": [{"id": 1, "name": "Meetings", "slug": "meetings"}]
  }
]

Notes:

• Only returns published events
• Results ordered by startDate ASC (upcoming first)
• endDate is optional

GET /api/events/:slug

Get a single published event by slug.

Response: Full event details including content and tags.

GET /api/people

Retrieve all published team members.

Response:

[
  {
    "id": 1,
    "name": "John Smith",
    "role": "President",
    "imageUrl": "/api/images/john-smith.jpg",
    "briefMessage": "Leading YCW Adelaide",
    "displayOrder": 0
  }
]

Notes:

• Only returns published people
• Results ordered by displayOrder ASC

Submissions & Engagement

POST /api/contact

Submit a contact form inquiry.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "subject": "General Inquiry",
  "message": "I have a question about YCW Adelaide programs..."
}

Success Response (200 OK):

{
  "success": true,
  "message": "Thank you for your message. We will get back to you soon!"
}

Error Responses:

• 400 Bad Request - Missing required fields or invalid email format

Notes:

• All fields are required: name, email, subject, message
• Email format is validated server-side
• Inputs are sanitized (trimmed, length-limited):
  • name: max 200 characters
  • email: max 200 characters (lowercased)
  • subject: max 200 characters
  • message: max 5000 characters
• Submission is stored in database for staff review
• Email notification may be sent (if configured)

POST /api/newsletter/subscribe

Subscribe to the newsletter.

Request Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "source": "website"
}

Success Response (200 OK):

{
  "success": true,
  "message": "Thank you for subscribing!"
}

Notes:

• email is required
• name is optional
• source is optional (tracks where subscription came from, e.g., "website", "mobile-app", "event")
• Email format is validated server-side
• Email is automatically lowercased and trimmed
• If email already exists:
  • If unsubscribed: re-subscribes them
  • If already subscribed: returns success message
• Inputs are sanitized:
  • email: max 200 characters, lowercased
  • name: max 200 characters (optional)
  • source: max 50 characters (optional, defaults to "unknown")

POST /api/newsletter/unsubscribe

Unsubscribe from newsletter.

Request Body:

{
  "email": "subscriber@example.com"
}

Success Response (200 OK):

{
  "success": true,
  "message": "Successfully unsubscribed"
}

Notes:

• Email is required
• Email format is validated
• Email is lowercased and trimmed
• Returns success even if email was not subscribed

POST /api/ycs/submit-action

Submit a YCS (Young Catholic Students) action proposal for review.

Request Body:

{
  "title": "Community Garden Project",
  "description": "Creating a community garden...",
  "content": "<p>Full proposal content...</p>",
  "imageUrls": [
    "/api/images/ycs-submissions/1703123456789-abc123.jpg"
  ],
  "contactName": "John Doe",
  "contactEmail": "john@example.com",
  "contactPhone": "0412345678"
}

Success Response (200 OK):

{
  "success": true,
  "message": "Action submitted successfully",
  "id": 123
}

Notes:

• title, description, contactName, contactEmail are required
• content, imageUrls, contactPhone are optional
• imageUrls should use URLs from /api/ycs/upload/image
• Submission is stored for staff review
• Email notification sent to staff

POST /api/ycs/upload/image

Upload an image for YCS action submission.

Request Body (FormData):

file: <File object>

Success Response (200 OK):

{
  "url": "/api/images/ycs-submissions/1703123456789-abc123def456.jpg",
  "key": "ycs-submissions/1703123456789-abc123def456.jpg",
  "filename": "1703123456789-abc123def456.jpg"
}

Notes:

• Allowed file types: image/jpeg, image/jpg, image/png, image/webp, image/gif
• Images stored in ycs-submissions/ folder in R2
• Filename auto-generated with timestamp and random string
• Use returned url in imageUrls array when submitting action
• No duplicate detection (unlike staff image upload)

Organization & Discovery

GET /api/tags

Retrieve all tags.

Response:

[
  {
    "id": 1,
    "name": "Events",
    "slug": "events"
  }
]

Notes:

• Results ordered by name ASC
• Used for filtering content

GET /api/navigation

Get the complete navigation structure including static pages and custom pages.

Response:

[
  {
    "id": "static-home",
    "label": "Home",
    "path": "/",
    "isCustom": false,
    "order": 0
  },
  {
    "id": "static-actions",
    "label": "Actions",
    "path": "/actions",
    "isCustom": false,
    "order": 1
  },
  {
    "id": "custom-1",
    "label": "Custom Page",
    "path": "custom-page-slug",
    "isCustom": true,
    "customPageId": 1,
    "order": 7
  },
  {
    "id": "nav-1",
    "label": "Folder",
    "path": null,
    "isCustom": false,
    "isFolder": true,
    "order": 8,
    "children": [
      {
        "id": "custom-2",
        "label": "Nested Page",
        "path": "nested-page-slug",
        "isCustom": true,
        "customPageId": 2,
        "order": 0
      }
    ]
  }
]

Notes:

• Includes static pages (Home, Actions, Events, About, News, People, Contact)
• Includes custom pages created by staff
• Supports nested navigation (folders with children)
• Results ordered by order ASC

GET /api/about

Get about page content including mission, history, and values.

Response:

{
  "mission": {
    "title": "Our Mission",
    "content": "YCW Adelaide is committed to empowering young people..."
  },
  "history": {
    "title": "Our History",
    "content": "YCW Adelaide has been serving the community since 1950..."
  },
  "values": [
    {
      "id": 1,
      "title": "Faith",
      "description": "We are guided by our Catholic faith and values",
      "icon": "HeartIcon",
      "colorClass": "text-red-600"
    }
  ]
}

Notes:

• mission contains mission statement (title and content)
• history contains organization history (title and content)
• values is an array of core values
• Each value has: id, title, description, icon (Heroicon name), colorClass (Tailwind CSS class)
• Values ordered by displayOrder ASC, then id ASC
• Content may be HTML formatted

GET /api/actions/:id/related

Get related actions based on shared tags.

Response:

[
  {
    "id": 2,
    "title": "Related Action",
    "slug": "related-action",
    "description": "Related action description",
    "icon": "HeartIcon",
    "gradientClass": "from-red-500 to-pink-500",
    "accentClass": "text-red-600",
    "coverImageUrl": "/api/images/related.jpg"
  }
]

Notes:

• Returns up to 3 related actions
• Related actions determined by shared tags
• Only returns published actions
• Results exclude the current action
• Returns empty array if no related actions found

GET /api/news/:id/related

Get related news articles based on shared tags or category.

Response:

[
  {
    "id": 3,
    "title": "Related Article",
    "slug": "related-article",
    "description": "Related article description",
    "category": "Events",
    "imageUrl": "/api/images/related.jpg",
    "publishedAt": "2024-11-20T10:00:00.000Z"
  }
]

Notes:

• Returns up to 3 related articles
• Related articles determined by shared tags or same category
• Only returns published articles
• Results exclude the current article
• Returns empty array if no related articles found

GET /api/static-images

Retrieve all static images with their specifications and guidelines.

Response:

[
  {
    "id": "logo",
    "name": "YCW Adelaide Logo",
    "description": "Main logo for YCW Adelaide",
    "imageUrl": "/api/images/ycw-logo.png",
    "recommendedFormat": "PNG",
    "recommendedSize": "1200x600px",
    "contentDescription": "YCW Adelaide logo featuring the organization name and emblem"
  }
]

Notes:

• Results ordered by id ASC
• id is a unique identifier (string)
• recommendedFormat is the recommended file format
• recommendedSize is the recommended dimensions
• contentDescription is optional alt text/accessibility description

GET /api/static-images/:id

Get a single static image by ID.

Response: Single static image object with same structure as above.

Feeds & SEO

GET /api/feed/news

RSS feed for published news articles.

Content-Type: application/rss+xml; charset=UTF-8

Response: XML RSS feed (RSS 2.0 format)

Notes:

• Returns up to 50 most recent published news articles
• Results ordered by publishedAt DESC
• Feed is cached for 1 hour (3600 seconds)
• Includes full article content in content:encoded
• Includes image enclosures if available
• Includes category information
• Uses ISO 8601 dates converted to RFC 822 format

GET /api/feed/events

RSS feed for published events.

Content-Type: application/rss+xml; charset=UTF-8

Response: XML RSS feed (RSS 2.0 format)

Notes:

• Returns up to 50 most recent published events
• Results ordered by startDate ASC (upcoming first)
• Feed is cached for 1 hour (3600 seconds)
• Includes full event content in content:encoded
• Includes image enclosures if available
• Includes location and date information
• Uses ISO 8601 dates converted to RFC 822 format

GET /sitemap.xml

XML sitemap for SEO.

Content-Type: application/xml; charset=UTF-8

Response: XML sitemap

Notes:

• Sitemap is cached for 24 hours (86400 seconds)
• Includes all published content:
  • Static pages (Home, Actions, Events, About, News, People, Contact)
  • Published actions (with slugs)
  • Published news articles (with slugs)
  • Published events (with slugs)
  • Published custom pages (with slugs)
• lastmod is the last update date (YYYY-MM-DD format)
• changefreq indicates how often content changes:
  • daily - Frequently updated pages
  • weekly - Content pages
  • monthly - Static/infrequent pages
• priority indicates page importance (0.0 to 1.0):
  • 1.0 - Homepage
  • 0.8 - Main section pages
  • 0.7 - Individual content pages

GET /robots.txt

Robots.txt file for search engine crawlers.

Content-Type: text/plain

Response:

User-agent: *
Allow: /
Disallow: /staff/
Disallow: /api/staff/
Sitemap: https://ycwadelaide.adenmgb.com/sitemap.xml

Notes:

• Standard robots.txt format
• Allows all crawlers (User-agent: *)
• Allows crawling of public content (Allow: /)
• Disallows staff/admin areas (Disallow: /staff/, Disallow: /api/staff/)
• References sitemap location (Sitemap: ...)
• Used by search engines to understand crawl permissions

Common Patterns

Error Handling

All endpoints return consistent error format:

{
  "error": "Error message description"
}

Status Codes

• 200 OK - Success
• 400 Bad Request - Invalid input/data
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Date Formats

All dates use ISO 8601 format: 2024-12-15T10:30:00.000Z (UTC)

Filtering

Many list endpoints support query parameters:

• tag - Filter by tag slug
• search - Search by name/title
• limit - Limit number of results
• offset - Pagination offset

CORS

All endpoints support CORS with:

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization

Rate Limiting

Currently no rate limiting is implemented. Consider implementing client-side rate limiting for production mobile apps.

Mobile Implementation Tips

1. Caching - Cache content locally for offline access
2. Pagination - Implement pagination for large lists
3. Image Optimization - Use appropriate image sizes for mobile
4. Error Handling - Show user-friendly error messages
5. Loading States - Show loading indicators for all requests
6. Offline Support - Cache frequently accessed content
7. Search - Implement client-side search/filtering
8. Pull to Refresh - Implement pull-to-refresh for content lists

Complete API Reference

This document provides complete documentation for all public API endpoints. Use the links below to jump to specific sections:

Content APIs

• Actions - Browse and view published YCW actions
• News - Browse and view published news articles
• Events - Browse and view published events
• People - View published team members
• About - Get about page content (mission, history, values)

Organization & Discovery

• Tags - Browse tags for filtering content
• Navigation - Get website navigation structure
• Related Content - Get related content suggestions

Submissions & Engagement

• Contact - Submit contact form
• Newsletter - Subscribe/unsubscribe to newsletter
• YCS Submissions - Submit YCS action proposals

Media & Assets

• Static Images - Get static image information
• YCS Image Upload - Upload images for YCS submissions

Feeds & SEO

• RSS Feeds - RSS feeds for news and events
• Sitemap - XML sitemap for SEO
• Robots - Robots.txt file

Related Guides

• Content APIs - Staff content management
• Media APIs - Image access