dc-rest/documentation/blogs.yaml

swagger: '2.0'
info:
  title: Dotclear API
  description: Manage your(s) blogs with this API
  version: 0.0.2
host: dotclear.localhost
schemes:
  - http
basePath: /dotclear/index.php?rest
produces:
  - application/json
paths:

  /blogs:
    get:
      summary: Get list of availables blogs
      parameters:
        - name: x_dc_key
          in: header
          required: false
          type: string
      responses:
        '200':
          description: array serving blogs properties
          schema:
            type: array
            items:
              type: string
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Create a new blog
      parameters:
        - name: x_dc_key
          in: header
          type: string
          required: true
        - name: blog
          in: body
          description: The blog you want to create
          schema:
            $ref: '#/definitions/blog'
          required: true
      responses:
        '201':
          description: 'Success, array containing the new blog''s identifiant'
          schema:
            type: object
            properties:
              code:
                type: integer
              blog_id:
                type: integer
              message:
                type: string
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  '/blogs/{blog-id}':
    get:
      summary: Get a blog poperties
      parameters:
        - name: x_dc_key
          in: header
          type: string
          required: false
        - name: blog-id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: 'Core blog properties. use {blog_id}/settings methods for more settings.'
          schema:
            $ref: '#/definitions/blogProperties'
        '404':
          description: this blog id does not exists
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: Update part of blog properties
      parameters:
        - name: x_dc_key
          in: header
          type: string
          required: true
        - name: blog-id
          in: path
          type: string
          required: true
        - name: blog
          in: body
          description: This list of parameters is not exhaustive
          required: true
          schema:
            $ref: '#/definitions/blogProperties'
      responses:
        '200':
          description: array containing the edited blog's identifiant
          schema:
            $ref: '#/definitions/Ids'
        '404':
          description: this blog id does not exists
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      summary: 'Overwrite blog Properties (if an optional parameter is not set, his value will be erased by the default value)'
      parameters:
        - name: x_dc_key
          in: header
          type: string
          required: true
        - name: blog-id
          in: path
          type: string
          required: true
        - name: blog
          in: body
          description: This list of parameters is not exhaustive
          required: true
          schema:
            $ref: '#/definitions/blogPropertiesPut'
      responses:
        '200':
          description: array containing the edited blog's identifiant
          schema:
            $ref: '#/definitions/Ids'
        '404':
          description: this blog id does not exists
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    delete:
      summary: Delete this blog
      parameters:
        - name: x_dc_key
          in: header
          type: string
          required: true
        - name: blog-id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: array containing the deleted blog's identifiant
          schema:
            $ref: '#/definitions/Ids'
        '404':
          description: this blog id does not exists
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

definitions:
  blog:
    type: object
    required:
      - blog_id
      - blog_name
      - blog_url
    properties:
      blog_id:
        type: string
      blog_name:
        type: string
      blog_url:
        type: string
      blog_desc:
        type: string
      lang:
        type: string
      blog_timezone:
        type: string
      url_scan:
        type: string
        enum:
          - query_string
          - path_info
  Ids:
    type: object
    properties:
      id:
        type: integer
        description: New blog id
  blogPropertiesPut:
    required:
      - blog_id
      - blog_name
      - blog_url
      - blog_desc
    type: object
    properties:
      blog_id:
        type: string
      blog_name:
        type: string
      blog_url:
        type: string
      blog_desc:
        type: string
  blogProperties:
    type: object
    properties:
      blog_id:
        type: string
      blog_name:
        type: string
      blog_url:
        type: string
      blog_desc:
        type: string
    
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string