URL Generation Guide for Frontend Developers

Overview

As part of our content management system (CMS), we need to implement a URL generation feature for certain resources. Your role is to create an API endpoint that will generate appropriate URLs based on the resource data provided.

Key Points

1. Our URL Generation service will make requests to your API when a URL needs to be created or updated.
2. You will receive the full resource data for URL generation.
3. Only whitelisted resource types will be sent to your API for URL generation.
4. The generated URLs are managed automatically; CMS editors or other tools cannot manually alter these URLs.
5. The endpoint for URL generation will be configurable per tenant.

API Specification

Endpoint

You need to implement an endpoint for URL generation. The exact endpoint URL will be configurable per tenant.

Request Format

The request will be sent as JSON in the following format:

JSON

{
  "project_domain": "string",  // This is the tenant identifier
  "id": "string",
  "type": "string",
  "action": "string",
  "object": {
    "data": {
      // Varies by resource type
      // Structure will be the same as GET /{resource}/{id} in Content API
    }
  }
}

Response Format

Your API should respond with a JSON object containing the generated URL:

JSON

{
  "url": "string"
}

Error Handling

If there's an error in URL generation, respond with an appropriate HTTP status code (e.g., 400 for bad request, 500 for server error) and include an error message in the response body:

JSON

{
  "error": "string"
}

Implementation Guidelines

1. Resource-specific Logic: Implement URL generation logic for each whitelisted resource type. The structure of the object.data in the request will vary based on the resource type and will match the GET /{resource}/{id} response in the Content API.

2. Tenant-aware: Use the project_domain to generate tenant-specific URLs.

3. Action-aware: The action field in the request may indicate the type of operation (e.g., "create", "update"). Consider this when generating URLs if necessary.

4. Idempotency: Ensure that your URL generation is idempotent. Given the same input data, it should always produce the same URL.

5. Performance: Optimize your URL generation logic for performance, as it may be called frequently.

6. Validation: Implement proper input validation. If required data is missing or invalid, return an appropriate error response.

7. Logging: Implement logging in your API to help with debugging and monitoring.

Example

Here's a simple example of how your API might be called and should respond:

Request:

JSON

POST https://url-generator.tenant1.com/generate-url
{
  "project_domain": "tenant1.com",
  "id": "12345",
  "type": "article",
  "action": "create",
  "object": {
    "data": {
      "title": "How to Generate URLs",
      "category": "Web Development",
      "publishDate": "2023-09-20"
    }
  }
}

Response:

JSON

{
  "url": "https://tenant1.com/web-development/2023/09/20/how-to-generate-urls"
}

Next Steps

1. Implement the URL generation endpoint according to this specification.
2. Make sure that the endpoint returns the correct URL according to the tenant specific rules for URL building
3. Optimize the endpoint for performance
4. Email support with the endpoint and the resources that need to have URLs generated