openapi: 3.0.3

info:
  title: MokoSuiteOpenGraph API
  version: 1.0.0
  description: |
    REST API for managing Open Graph, SEO meta, and structured-data tags in
    Joomla via the MokoSuiteOpenGraph extension.

    The API follows Joomla's Web Services conventions and returns responses in
    [JSON:API](https://jsonapi.org/) format. All endpoints require
    authentication via a Joomla API token.
  contact:
    name: Moko Consulting
    email: hello@mokoconsulting.tech
  license:
    name: GPL-3.0-or-later
    url: https://www.gnu.org/licenses/gpl-3.0.html

servers:
  - url: /api/index.php/v1
    description: Joomla Web Services API

security:
  - apiToken: []

tags:
  - name: Tags
    description: CRUD operations for Open Graph tag records

paths:
  /mokoog/tags:
    get:
      operationId: listTags
      summary: List OG tags
      description: |
        Returns a paginated collection of OG tag records. Supports filtering
        by content type, published state, and language.
      tags: [Tags]
      parameters:
        - name: "filter[content_type]"
          in: query
          description: Filter by content type (e.g. `com_content`, `menu`, `com_mokoshop`)
          schema:
            type: string
            example: com_content
        - name: "filter[content_id]"
          in: query
          description: Filter by content ID
          schema:
            type: integer
            example: 42
        - name: "filter[published]"
          in: query
          description: Filter by published state
          schema:
            type: integer
            enum: [0, 1]
        - name: "filter[language]"
          in: query
          description: Filter by language tag (e.g. `en-GB`, `*`)
          schema:
            type: string
            example: "*"
        - name: "filter[search]"
          in: query
          description: Free-text search across tag fields
          schema:
            type: string
        - name: "page[offset]"
          in: query
          description: Number of records to skip (pagination offset)
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: "page[limit]"
          in: query
          description: Maximum number of records to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: "list[fullordering]"
          in: query
          description: Sort order for results
          schema:
            type: string
            enum:
              - a.id ASC
              - a.id DESC
              - a.og_title ASC
              - a.og_title DESC
              - a.modified ASC
              - a.modified DESC
            default: a.modified DESC
      responses:
        "200":
          description: A JSON:API collection of OG tags
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/TagCollection"
              example:
                links:
                  self: "/api/index.php/v1/mokoog/tags"
                data:
                  - type: tags
                    id: "1"
                    attributes:
                      content_type: com_content
                      content_id: 42
                      og_title: "My Article Title"
                      og_description: "A brief description for social sharing."
                      og_image: "images/mokoog/og-banner.jpg"
                      og_type: article
                      seo_title: "My Article | Example Site"
                      meta_description: "A brief meta description for search engines."
                      robots: "index, follow"
                      canonical_url: "https://example.com/my-article"
                      language: "*"
                      published: 1
                      created: "2026-06-01T12:00:00+00:00"
                      modified: "2026-06-15T08:30:00+00:00"
                meta:
                  total-pages: 1
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: createTag
      summary: Create an OG tag
      description: |
        Creates a new OG tag record. The combination of `content_type`,
        `content_id`, and `language` must be unique.
      tags: [Tags]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagCreateRequest"
            example:
              content_type: com_content
              content_id: 42
              og_title: "My Article Title"
              og_description: "A brief description for social sharing."
              og_image: "images/mokoog/og-banner.jpg"
              og_type: article
              language: "*"
              published: 1
      responses:
        "200":
          description: The created tag
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/TagDocument"
              example:
                links:
                  self: "/api/index.php/v1/mokoog/tags/1"
                data:
                  type: tags
                  id: "1"
                  attributes:
                    content_type: com_content
                    content_id: 42
                    og_title: "My Article Title"
                    og_description: "A brief description for social sharing."
                    og_image: "images/mokoog/og-banner.jpg"
                    og_type: article
                    seo_title: ""
                    meta_description: ""
                    robots: ""
                    canonical_url: ""
                    language: "*"
                    published: 1
                    created: "2026-06-23T10:00:00+00:00"
                    modified: "2026-06-23T10:00:00+00:00"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /mokoog/tags/{id}:
    parameters:
      - $ref: "#/components/parameters/TagId"

    get:
      operationId: getTag
      summary: Get a single OG tag
      tags: [Tags]
      responses:
        "200":
          description: A single OG tag resource
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/TagDocument"
              example:
                links:
                  self: "/api/index.php/v1/mokoog/tags/1"
                data:
                  type: tags
                  id: "1"
                  attributes:
                    content_type: com_content
                    content_id: 42
                    og_title: "My Article Title"
                    og_description: "A brief description for social sharing."
                    og_image: "images/mokoog/og-banner.jpg"
                    og_type: article
                    seo_title: "My Article | Example Site"
                    meta_description: "A brief meta description for search engines."
                    robots: "index, follow"
                    canonical_url: "https://example.com/my-article"
                    language: "*"
                    published: 1
                    created: "2026-06-01T12:00:00+00:00"
                    modified: "2026-06-15T08:30:00+00:00"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

    patch:
      operationId: updateTag
      summary: Update an OG tag
      description: Partially updates an existing OG tag. Only supplied fields are changed.
      tags: [Tags]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TagUpdateRequest"
            example:
              og_title: "Updated Title"
              og_description: "Updated social description."
              published: 0
      responses:
        "200":
          description: The updated tag
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/TagDocument"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

    delete:
      operationId: deleteTag
      summary: Delete an OG tag
      tags: [Tags]
      responses:
        "204":
          description: Tag deleted successfully
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /mokoog/lookup/{content_type}/{content_id}:
    get:
      operationId: lookupTag
      summary: Look up an OG tag by content type and content ID
      description: |
        Resolves an OG tag by its `content_type` and `content_id` pair and
        returns the full tag resource. This is a convenience endpoint that
        avoids the caller needing to know the internal tag ID.
      tags: [Tags]
      parameters:
        - name: content_type
          in: path
          required: true
          description: |
            The content type identifier (e.g. `com_content`, `menu`,
            `com_mokoshop`). Must match the pattern `[a-z][a-z0-9_.]*`.
          schema:
            type: string
            pattern: "^[a-z][a-z0-9_.]*$"
            example: com_content
        - name: content_id
          in: path
          required: true
          description: The content item ID
          schema:
            type: integer
            minimum: 1
            example: 42
      responses:
        "200":
          description: The matching OG tag resource
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/TagDocument"
        "400":
          description: Missing or invalid content_type / content_id
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - title: Bad Request
                    status: 400
                    detail: "content_type and content_id are required"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: No OG tag found for the given content_type and content_id
          content:
            application/vnd.api+json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                errors:
                  - title: Not Found
                    status: 404
                    detail: "OG tag not found for com_content:42"

components:
  securitySchemes:
    apiToken:
      type: apiKey
      name: X-Joomla-Token
      in: header
      description: |
        Joomla API token. Can also be passed as the `api-token` query
        parameter. Generate a token from the Joomla administrator panel
        under Users > Manage > [user] > Joomla API Token tab.

  parameters:
    TagId:
      name: id
      in: path
      required: true
      description: The OG tag record ID
      schema:
        type: integer
        minimum: 1
        example: 1

  schemas:
    TagAttributes:
      type: object
      description: Full set of OG tag attributes returned by the API
      properties:
        content_type:
          type: string
          description: |
            Content type identifier (e.g. `com_content`, `menu`,
            `com_mokoshop`). Must match `[a-z][a-z0-9_.]*`.
          pattern: "^[a-z][a-z0-9_.]*$"
          maxLength: 100
          example: com_content
        content_id:
          type: integer
          description: The ID of the associated content item
          minimum: 1
          example: 42
        og_title:
          type: string
          description: Open Graph title (`og:title`)
          maxLength: 255
          example: "My Article Title"
        og_description:
          type: string
          description: Open Graph description (`og:description`)
          example: "A brief description for social sharing."
        og_image:
          type: string
          description: Relative path to the Open Graph image (`og:image`)
          maxLength: 512
          example: "images/mokoog/og-banner.jpg"
        og_type:
          type: string
          description: Open Graph type (`og:type`)
          default: article
          enum:
            - article
            - website
            - product
            - profile
            - book
            - music.song
            - music.album
            - video.movie
            - video.episode
            - video.other
          example: article
        seo_title:
          type: string
          description: SEO page title (used in `<title>` tag)
          maxLength: 70
          example: "My Article | Example Site"
        meta_description:
          type: string
          description: Meta description for search engines
          maxLength: 200
          example: "A brief meta description for search engines."
        robots:
          type: string
          description: |
            Comma-separated robots directives. Valid directives: `index`,
            `noindex`, `follow`, `nofollow`, `none`, `noarchive`,
            `nosnippet`, `noimageindex`, `max-snippet`, `max-image-preview`.
          maxLength: 100
          example: "index, follow"
        canonical_url:
          type: string
          format: uri
          description: Canonical URL for the page
          maxLength: 512
          example: "https://example.com/my-article"
        language:
          type: string
          description: Joomla language tag (`*` for all languages)
          maxLength: 7
          default: "*"
          example: "*"
        published:
          type: integer
          description: Published state (1 = published, 0 = unpublished)
          enum: [0, 1]
          default: 1
          example: 1
        created:
          type: string
          format: date-time
          description: Record creation timestamp (read-only)
          readOnly: true
          example: "2026-06-01T12:00:00+00:00"
        modified:
          type: string
          format: date-time
          description: Last modification timestamp (read-only)
          readOnly: true
          example: "2026-06-15T08:30:00+00:00"

    TagResource:
      type: object
      description: A single OG tag in JSON:API resource format
      required: [type, id, attributes]
      properties:
        type:
          type: string
          enum: [tags]
          example: tags
        id:
          type: string
          description: The record ID as a string (per JSON:API spec)
          example: "1"
        attributes:
          $ref: "#/components/schemas/TagAttributes"

    TagDocument:
      type: object
      description: JSON:API document containing a single tag resource
      properties:
        links:
          type: object
          properties:
            self:
              type: string
              example: "/api/index.php/v1/mokoog/tags/1"
        data:
          $ref: "#/components/schemas/TagResource"

    TagCollection:
      type: object
      description: JSON:API document containing a collection of tag resources
      properties:
        links:
          type: object
          properties:
            self:
              type: string
              example: "/api/index.php/v1/mokoog/tags"
        data:
          type: array
          items:
            $ref: "#/components/schemas/TagResource"
        meta:
          type: object
          properties:
            total-pages:
              type: integer
              description: Total number of pages available
              example: 1

    TagCreateRequest:
      type: object
      description: Request body for creating a new OG tag
      required:
        - content_type
        - content_id
      properties:
        content_type:
          type: string
          pattern: "^[a-z][a-z0-9_.]*$"
          maxLength: 100
          example: com_content
        content_id:
          type: integer
          minimum: 1
          example: 42
        og_title:
          type: string
          maxLength: 255
        og_description:
          type: string
        og_image:
          type: string
          maxLength: 512
        og_type:
          type: string
          default: article
          enum:
            - article
            - website
            - product
            - profile
            - book
            - music.song
            - music.album
            - video.movie
            - video.episode
            - video.other
        og_video:
          type: string
          format: uri
          description: Open Graph video URL (`og:video`)
          maxLength: 512
        seo_title:
          type: string
          maxLength: 70
        meta_description:
          type: string
          maxLength: 200
        robots:
          type: string
          maxLength: 100
        canonical_url:
          type: string
          format: uri
          maxLength: 512
        language:
          type: string
          maxLength: 7
          default: "*"
        published:
          type: integer
          enum: [0, 1]
          default: 1

    TagUpdateRequest:
      type: object
      description: |
        Request body for updating an OG tag. All fields are optional; only
        supplied fields are modified.
      properties:
        og_title:
          type: string
          maxLength: 255
        og_description:
          type: string
        og_image:
          type: string
          maxLength: 512
        og_type:
          type: string
          enum:
            - article
            - website
            - product
            - profile
            - book
            - music.song
            - music.album
            - video.movie
            - video.episode
            - video.other
        og_video:
          type: string
          format: uri
          maxLength: 512
        seo_title:
          type: string
          maxLength: 70
        meta_description:
          type: string
          maxLength: 200
        robots:
          type: string
          maxLength: 100
        canonical_url:
          type: string
          format: uri
          maxLength: 512
        language:
          type: string
          maxLength: 7
        published:
          type: integer
          enum: [0, 1]

    ErrorResponse:
      type: object
      description: JSON:API error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                example: Not Found
              status:
                type: integer
                example: 404
              detail:
                type: string
                example: "Item not found."

  responses:
    BadRequest:
      description: Invalid request data
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            errors:
              - title: Bad Request
                status: 400
                detail: "Content type is required."

    Unauthorized:
      description: Missing or invalid API token
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            errors:
              - title: Forbidden
                status: 403
                detail: "You are not authorised to access this resource."

    NotFound:
      description: Resource not found
      content:
        application/vnd.api+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            errors:
              - title: Not Found
                status: 404
                detail: "Item not found."