openapi: 3.1.0
info:
  title: CodeProject REST API
  description: >-
    CodeProject's REST API at api.codeproject.com provides read access to
    articles, forum messages, questions, and authenticated user profile data
    from the codeproject.com developer community. Authentication uses OAuth 2.0
    Bearer Tokens via Client Credentials, Authorization Code, or Implicit Grant
    flows. The "My" API set requires the Authorization Code or Implicit Grant
    flows because it accesses the signed-in user's resources, while the
    Articles, ForumMessages, and Questions endpoints can be accessed with a
    Client Credentials token. Tokens are sent in the Authorization header.
  version: '1.0-beta'
  contact:
    name: CodeProject API Support
    url: https://api.codeproject.com/Help
externalDocs:
  description: CodeProject API Help
  url: https://api.codeproject.com/Help
servers:
  - url: https://api.codeproject.com
    description: CodeProject Resource Server
tags:
  - name: Articles
    description: Articles, technical blogs, and tips and tricks (rating >= 3.0).
  - name: ForumMessages
    description: Latest messages for a forum or message thread.
  - name: Questions
    description: Q&A questions (new, active, unanswered).
  - name: My
    description: Authenticated user resources (answers, articles, blogs, bookmarks, notifications, profile, reputation, tips).
security:
  - oauth2: [read]
paths:
  /v1/Articles:
    get:
      operationId: listArticles
      summary: List the latest articles
      description: Retrieve the latest articles, technical blogs, and tips & tricks (rating >= 3.0), ordered by modified date.
      tags: [Articles]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: minRating
          in: query
          schema:
            type: number
            format: float
      responses:
        '200':
          description: Article list
  /v1/Articles/{id}:
    get:
      operationId: getArticle
      summary: Get a single article
      tags: [Articles]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Article detail
        '404':
          description: Not found
  /v1/ForumMessages/{forumId}:
    get:
      operationId: listForumMessages
      summary: List the latest messages for a forum
      tags: [ForumMessages]
      parameters:
        - name: forumId
          in: path
          required: true
          schema:
            type: integer
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Forum messages
  /v1/Questions:
    get:
      operationId: listQuestions
      summary: List Q&A questions
      tags: [Questions]
      parameters:
        - name: filter
          in: query
          description: Filter set - new, active, unanswered.
          schema:
            type: string
            enum: [new, active, unanswered]
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Question list
  /v1/Questions/{id}:
    get:
      operationId: getQuestion
      summary: Get a question and its answers
      tags: [Questions]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Question detail
  /v1/My/Profile:
    get:
      operationId: getMyProfile
      summary: Get the authenticated user's profile
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Profile
        '401':
          description: Unauthorized
  /v1/My/Reputation:
    get:
      operationId: getMyReputation
      summary: Get the authenticated user's reputation
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Reputation
        '401':
          description: Unauthorized
  /v1/My/Articles:
    get:
      operationId: listMyArticles
      summary: List the authenticated user's articles
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Articles
        '401':
          description: Unauthorized
  /v1/My/Answers:
    get:
      operationId: listMyAnswers
      summary: List the authenticated user's answers
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Answers
        '401':
          description: Unauthorized
  /v1/My/Blog:
    get:
      operationId: listMyBlogPosts
      summary: List the authenticated user's blog posts
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Blog posts
        '401':
          description: Unauthorized
  /v1/My/Bookmarks:
    get:
      operationId: listMyBookmarks
      summary: List the authenticated user's bookmarks
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Bookmarks
        '401':
          description: Unauthorized
  /v1/My/Notifications:
    get:
      operationId: listMyNotifications
      summary: List the authenticated user's notifications
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Notifications
        '401':
          description: Unauthorized
  /v1/My/Tips:
    get:
      operationId: listMyTips
      summary: List the authenticated user's tips
      tags: [My]
      security:
        - oauth2: [read]
      responses:
        '200':
          description: Tips
        '401':
          description: Unauthorized
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0 Bearer Tokens are issued by the CodeProject identity server.
        Use Client Credentials Grant for read access to public resources and
        Authorization Code Grant or Implicit Grant for the My API.
      flows:
        clientCredentials:
          tokenUrl: https://api.codeproject.com/Token
          scopes:
            read: Read access to public resources
        authorizationCode:
          authorizationUrl: https://api.codeproject.com/Authorize
          tokenUrl: https://api.codeproject.com/Token
          scopes:
            read: Read access to public and user-owned resources
        implicit:
          authorizationUrl: https://api.codeproject.com/Authorize
          scopes:
            read: Read access to public and user-owned resources