Skip to main content

News Article by ID API

Overview​

The News Article by ID API allows users to retrieve, update, and delete specific news articles using their unique identifier or slug. This endpoint supports role-based access control and automatic view tracking.

Endpoint Details​

  • URL: /api/news/[id]
  • Methods: GET, PUT, DELETE
  • Authentication: Required for PUT/DELETE operations
  • Rate Limit: 120 requests per minute for GET, 30 for PUT/DELETE

GET - Retrieve News Article​

Request Format​

GET /api/news/{id_or_slug}

URL Parameters​

  • id (string, required): The unique identifier or slug of the news article

Response Format​

Success Response (200 OK)​

{
  "success": true,
  "data": {
    "id": "news_123456789",
    "title": "Ring Platform Launches New Features",
    "content": "We are excited to announce the launch of several new features...",
    "excerpt": "Ring Platform introduces new features to enhance user experience",
    "slug": "ring-platform-launches-new-features",
    "category": "Product Updates",
    "tags": ["features", "announcement", "platform"],
    "featuredImage": "https://storage.example.com/news/featured-image.jpg",
    "gallery": [
      "https://storage.example.com/news/gallery1.jpg",
      "https://storage.example.com/news/gallery2.jpg"
    ],
    "visibility": "public",
    "status": "published",
    "featured": true,
    "views": 1251,
    "publishedAt": "2025-01-14T10:00:00Z",
    "createdAt": "2025-01-14T09:30:00Z",
    "updatedAt": "2025-01-14T17:20:00Z",
    "authorId": "user_987654321",
    "seo": {
      "metaTitle": "Ring Platform Launches New Features",
      "metaDescription": "Discover the latest features and improvements in Ring Platform",
      "keywords": ["ring platform", "new features", "tech news"]
    }
  }
}

Error Responses​

// 404 Not Found
{
  "success": false,
  "error": "News article not found"
}

// 500 Internal Server Error
{
  "success": false,
  "error": "Failed to fetch news article"
}

Code Examples​

JavaScript/TypeScript​

async function getNewsArticle(idOrSlug: string) {
  const response = await fetch(`/api/news/${idOrSlug}`);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }
  
  const result = await response.json();
  return result.data;
}

// Usage
const article = await getNewsArticle('ring-platform-launches-new-features');

cURL Example​

curl -X GET https://ring.ck.ua/api/news/ring-platform-launches-new-features

PUT - Update News Article​

Authentication Requirements​

  • Required Role: ADMIN only
  • Authentication: JWT Token required

Request Format​

PUT /api/news/{id}
Content-Type: application/json
Authorization: Bearer <jwt_token>

Request Body Schema​

interface UpdateNewsRequest {
  title?: string;
  content?: string;
  excerpt?: string;
  slug?: string;
  category?: string;
  tags?: string[];
  featuredImage?: string;
  gallery?: string[];
  visibility?: 'public' | 'member' | 'confidential';
  status?: 'draft' | 'published' | 'archived';
  featured?: boolean;
  seo?: {
    metaTitle?: string;
    metaDescription?: string;
    keywords?: string[];
  };
}

Example Request Body​

{
  "title": "Updated: Ring Platform Launches New Features",
  "content": "We are excited to announce the launch of several new features that will enhance your experience...",
  "excerpt": "Ring Platform introduces groundbreaking new features",
  "category": "Major Updates",
  "tags": ["features", "announcement", "platform", "update"],
  "featured": true,
  "status": "published",
  "seo": {
    "metaTitle": "Updated: Ring Platform New Features Launch",
    "metaDescription": "Discover the latest groundbreaking features in Ring Platform",
    "keywords": ["ring platform", "new features", "major update"]
  }
}

Response Format​

Success Response (200 OK)​

{
  "success": true,
  "data": {
    "id": "news_123456789",
    "title": "Updated: Ring Platform Launches New Features",
    "content": "We are excited to announce the launch of several new features that will enhance your experience...",
    "excerpt": "Ring Platform introduces groundbreaking new features",
    "slug": "ring-platform-launches-new-features",
    "category": "Major Updates",
    "tags": ["features", "announcement", "platform", "update"],
    "status": "published",
    "featured": true,
    "updatedAt": "2025-01-14T17:25:00Z"
  },
  "message": "News article updated successfully"
}

Error Responses​

// 401 Unauthorized
{
  "success": false,
  "error": "Authentication required"
}

// 403 Forbidden
{
  "success": false,
  "error": "Admin access required"
}

// 404 Not Found
{
  "success": false,
  "error": "News article not found"
}

// 400 Bad Request (slug conflict)
{
  "success": false,
  "error": "Article with this slug already exists"
}

Code Examples​

JavaScript/TypeScript​

async function updateNewsArticle(id: string, updateData: UpdateNewsRequest) {
  const response = await fetch(`/api/news/${id}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(updateData)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

cURL Example​

curl -X PUT https://ring.ck.ua/api/news/news_123456789 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "title": "Updated: Ring Platform Launches New Features",
    "featured": true,
    "status": "published"
  }'

DELETE - Delete News Article​

Authentication Requirements​

  • Required Role: ADMIN only
  • Authentication: JWT Token required

Request Format​

DELETE /api/news/{id}
Authorization: Bearer <jwt_token>

Response Format​

Success Response (200 OK)​

{
  "success": true,
  "message": "News article deleted successfully"
}

Error Responses​

// 401 Unauthorized
{
  "success": false,
  "error": "Authentication required"
}

// 403 Forbidden
{
  "success": false,
  "error": "Admin access required"
}

// 404 Not Found
{
  "success": false,
  "error": "News article not found"
}

Code Examples​

JavaScript/TypeScript​

async function deleteNewsArticle(id: string) {
  const response = await fetch(`/api/news/${id}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

cURL Example​

curl -X DELETE https://ring.ck.ua/api/news/news_123456789 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Features​

Automatic View Tracking​

  • GET requests automatically increment the view count
  • View count is updated in real-time
  • Useful for analytics and trending content

Flexible Lookup​

  • Articles can be retrieved by ID or slug
  • Slug lookup enables SEO-friendly URLs
  • Automatic fallback from ID to slug lookup

SEO Support​

  • Comprehensive SEO metadata support
  • Meta titles, descriptions, and keywords
  • Slug-based URLs for better search engine optimization

Validation Rules​

Update Validation​

  • title: 1-200 characters
  • excerpt: 1-500 characters
  • slug: Must be unique, URL-friendly format
  • category: Must be valid category
  • tags: Maximum 10 tags, each 1-50 characters
  • visibility: Must be 'public', 'member', or 'confidential'
  • status: Must be 'draft', 'published', or 'archived'

Security Considerations​

  1. Role-Based Access: Only admins can update/delete articles
  2. Input Validation: All input is validated and sanitized
  3. Slug Uniqueness: Prevents duplicate slug conflicts
  4. Audit Logging: All modifications are logged
  5. Rate Limiting: Prevents abuse with appropriate limits

Changelog​

  • v1.0.0 - Initial implementation with basic CRUD operations
  • v1.1.0 - Added slug-based lookup and SEO support
  • v1.2.0 - Enhanced validation and error handling
  • v1.3.0 - Added automatic view tracking
  • v1.4.0 - Improved admin access controls