openapi.yaml

openapi: 3.1.0

info:
  version: 1.0.0
  title: therssproject v1 REST API
  description: therssproject's v1 REST API
  contact:
    name: Support
    url: https://therssproject.com

servers:
- url: https://api.therssproject.com

externalDocs:
  description: therssproject's v1 REST API
  url: https://www.therssproject.com/documentation

security:
  - ApiKeyAuthentication: []

paths:

  "/v1/feeds":
    get:
      summary: Get a parsed feed based on the given URL
      description: Get a parsed feed based on the given URL
      operationId: application/get-feeds
      parameters:
        - name: url
          in: query
          description: The URL of the feed to parse
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Feed"
        '401':
          $ref: '#/components/responses/Unauthorized'

  "/v1/subscriptions":
    # Create a new subscription
    post:
      summary: Create a new feed subscription
      description: Create a new feed subscription based on the given URL
      operationId: application/create-subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - endpoint
              properties:
                url:
                  type: string
                  description: The URL of the feed to parse
                endpoint:
                  type: string
                  description: The endpoint ID. (Make sure to create the endpoint first)
                metadata:
                  type: object
                  description: Optional metadata to be stored with the subscription. This
                    attribute is sent on webhooks. It is usually used to store information
                    from external systems to easily identify the subscription.
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Subscription"
        '401':
          $ref: '#/components/responses/Unauthorized'

    # Query subscriptions
    get:
      summary: Query subscriptions
      description: Query subscriptions
      operationId: application/query-subscription
      parameters:
        - name: from
          in: query
          description: ISO string date representing the start date
          required: false
          schema:
            type: string

      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Subscription"
        '401':
          $ref: '#/components/responses/Unauthorized'

  "/v1/subscriptions/{subscription_id}":
    # Get subscription by ID
    get:
      summary: Get subscription by ID
      description: Get subscription by ID
      operationId: application/get-subscription
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Subscription"
        '401':
          $ref: '#/components/responses/Unauthorized'

    # Remove subscription by ID
    delete:
      summary: Remove a subscription by ID
      description: Removes a subscription by ID
      operationId: application/remove-subscription
      responses:
        '204':
          description: Response
        '401':
          $ref: '#/components/responses/Unauthorized'

  "/v1/endpoints":
    # Create a new endpoint
    post:
      summary: Create a new endpoint
      description: Create a new endpoint
      operationId: application/create-endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - title
              properties:
                url:
                  type: string
                  description: The URL of the endpoint
                  example: https://api.mycoolproject.com/v1/webhooks/thressproject
                title:
                  type: string
                  description: The endpoint title
                  example: My production endpoint
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Endpoint"
        '401':
          $ref: '#/components/responses/Unauthorized'

    # Query endpoints
    get:
      summary: Query endpoints
      description: Query endpoints
      operationId: application/query-endpoint
      parameters:
        - name: from
          in: query
          description: ISO string date representing the start date
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Endpoint"
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  schemas:
    # Feed schema
    Feed:
      type: object
      required:
        - feed_type
        - entries
      properties:
        feed_type:
          type: string
          enum: [atom, json, rss0, rss1, rss2]
        title:
          type: string
        description:
          type: string
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Entry'

    # Entry schema
    Entry:
      type: object
      properties:
        url:
          type: string
        title:
          type: string
        description:
          type: string
        published_at:
          type: string

    # Subscription schema
    Subscription:
      type: object
      required:
        - id
        - url
        - endpoint
        - created_at
      properties:
        id:
          type: string
        url:
          type: string
        endpoint:
          type: string
        metadata:
          type: object
          description: Optional metadata to be stored with the subscription. This
            attribute is sent on webhooks. It is usually used to store information
            from external systems to easily identify the subscription.
        created_at:
          type: string

    # Endpoint schema
    Endpoint:
      type: object
      required:
        - id
        - application
        - url
        - title
        - created_at
        - updated_at
      properties:
        id:
          type: string
        application:
          type: string
        url:
          type: string
        title:
          type: string
        created_at:
          type: string
        updated_at:
          type: string

  securitySchemes:
    ApiKeyAuthentication:
      type: apiKey
      in: header
      name: Authorization

  responses:
    Unauthorized:
      description: Authentication information is missing or invalid