API.v2.yaml

openapi: 3.0.0
info:
  title: BecauseOfProg API
  version: '2.0'
  description: |-
    Welcome on the BecauseOfProg's API ! From there, you can fetch data available on our website :

    - Users registered on the website
    - Publications written on the blog and the devblogs
    - Comments submitted by users on publications

    First of all, you need a URL in order to access it. The root URL for the API is `https://api.becauseofprog.fr`. This URL is followed by the version of this format : `v{number}`. You can find versions below:

    | Version | Status     |
    | ------- | ---------- |
    | 2       | Available  |
    | 1       | Deprecated |

    ## Requests

    Every request to the API that require a body must be JSON-formatted, with the `Content-Type` header properly set to `application/json`: otherwise, a `400 Bad Request` status is returned.

    ### Authentication

    To access some endpoints, the user must be authenticated by grabbing its token on the `/auth` endpoint. This token is placed in the `Authorization` header of the request in question. If the user isn't authenticated when this is mandatory, a `401 Unauthorized` status is returned.

    ### Permissions

    Permissions indicate which actions a user can do on the API. A single one can have many permissions.

    | Name            | Bitwise value | Resource                      | Description                          | Granted to                     |
    | --------------- | ----------------------------- | ------------------------------------ | ------------------------------ |
    | `USER_WRITE`    | 2             |  Users                         | Allow editing any user               | BecauseOfProg members, moderators |
    | `BLOG_WRITE`    | 4             | Publications                  | Allow writing blog publications.     | BecauseOfProg members, blog writters |
    | `DEVBLOG_WRITE` | 8             | Devblogs                      | Allows writing posts for the devblog | BecauseOfProg members                     |

    If the user doesn't have the required permission on an endpoint, a `403 Forbidden` status is returned.

    ### Rate limiting

    In order to prevent spamming on the API, a system limits the number of possible requests per time interval. This is all detailed in response headers:

    - The `X-Ratelimit-Limit` header provides the maximum number of requests possible before limiting
    - The `X-Ratelimit-Remaining` header indicates the number of remaining requests
    - The `X-Ratelimit-Reset` is the number of seconds remaining before the number of possible requests returns back to the allowed amount

    **By default, the limit of requests is 5 and the time interval is 5 seconds.** If this limit is reached, a `429 Too Many Requests` status is returned.

    ## Responses

    Every response is in JSON format (with `Content-Type` header properly set to `application/json`), either an object or an array depending on the endpoint. Data can be empty, especially for entity creation or deletion.

    ### Pagination

    Some requests can return a lot of database entries, that make the client request slower and the API overloaded. To overcome this problem, endpoints in question integrate a system to prevent overloaded responses.

    **By default, the first `X` entries are returned** (X is defined for each entity). To get the next `x` entries, you must add the `skip` query parameter. Moreover, you can pass the `size` param to get less entities (from 1 to `X`). The total amount of entities is available under the `Count` header. If you go past this number, the data will obviously be empty.
  license:
    name: MIT
    url: 'https://github.com/BecauseOfProg/api-definition/blob/master/LICENSE'
  contact:
    name: BecauseOfProg staff
    email: contact@becauseofprog.fr
    url: 'https://twitter.com/BecauseOfProg'
servers:
  - url: 'https://api.becauseofprog.fr/v2'
paths:
  /users:
    get:
      summary: Get users
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/user'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: get-users
      description: "Get all the users.\n\n\U0001F510 Authentication - `USER_WRITE` permission\n\U0001F4DC Pagination - Max. 25 entities"
      parameters:
        - schema:
            type: string
          in: header
          name: Authorization
        - schema:
            type: string
          in: query
          name: name
          description: search by display name or user name
        - schema:
            type: string
          in: query
          name: email
          description: search by email
    post:
      summary: Create user
      responses:
        '201':
          description: Created
      operationId: create-user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: user's email adress
                  pattern: '(?:[a-z0-9!#$%&''*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&''*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])'
                username:
                  type: string
                  description: 'username, will be taken in the profile URL'
                  minLength: 2
                  maxLength: 32
                password:
                  type: string
                  description: user's password (be careful to choose strong enough one)
              required:
                - email
                - username
                - password
      description: |-
        **This endpoint isn't available for the moment. We're considering changing our users system.**

        Create a new user. Will be asked to verify their email address.
      tags:
        - Users
  '/users/{username}':
    parameters:
      - schema:
          type: string
        name: username
        in: path
        required: true
    get:
      summary: Get user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
      operationId: get-user
      description: Get user's informations based on their username.
      tags:
        - Users
    patch:
      summary: Edit user's profile
      operationId: edit-user
      responses:
        '204':
          description: No Content
      description: "Edit the user's profile informations.\n\n\U0001F510 Authentication - `USER_WRITE` permission OR user theyselves"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                displayname:
                  type: string
                  minLength: 2
                  maxLength: 32
                picture:
                  type: string
                description:
                  type: string
                biography:
                  type: string
                locations:
                  type: string
                socials:
                  type: array
                  items:
                    $ref: '#/components/schemas/social'
      parameters: []
      tags:
        - Users
  '/users/{username}/permissions':
    parameters:
      - schema:
          type: string
        name: username
        in: path
        required: true
    patch:
      summary: Edit user's permissions
      operationId: edit-user-permissions
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Edit permissions a user has, to grant or limit access to resources.\n\n\U0001F510 Authentication - `USER_WRITE` permission"
      parameters:
        - schema:
            type: string
          in: header
          name: Authorization
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                permissions:
                  type: array
                  items:
                    type: string
              required:
                - permissions
      tags:
        - Users
  /publications:
    get:
      summary: Get all publications
      tags:
        - Publications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/publication'
          headers:
            Pages:
              schema:
                type: string
              description: Total number of pages available
      operationId: get-publications
      description: "Get all the publications. Returns a list of publications without the content.\n\n\U0001F4DC Pagination - Max. 10 entities"
      parameters:
        - schema:
            type: string
          in: query
          name: category
          description: publication's category
        - schema:
            type: string
          in: query
          name: type
          description: publication's type (article / tutorial / flash)
        - schema:
            type: string
          in: query
          name: search
          description: 'search for publications (text inside title, description or content)'
        - schema:
            type: string
          in: query
          name: author
          description: search for publications written by a specific author (using their username)
        - schema:
            type: string
          in: query
          name: locale
          description: search for publications written in a specific lang
    parameters: []
    post:
      summary: Create a publication
      operationId: post-publication
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Write a new publication and publish it.\n\n\U0001F510 Authentication - `BLOG_WRITE` permission"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                type:
                  type: string
                category:
                  type: string
                keywords:
                  type: string
                illustration:
                  type: string
                content:
                  type: string
                locale:
                  type: string
                  default: fr
              required:
                - title
                - type
                - category
                - keywords
                - illustration
                - content
      tags:
        - Publications
  /auth:
    post:
      summary: Authenticate user
      tags:
        - Users
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      operationId: post-auth
      description: 'Get the token of a user, in order to interact with some parts of the API. To use authentication in requests that require it, add the `Authorization` header containing the token (inside returned data).'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: User's email address
                password:
                  type: string
                  description: 'User''s password, in clear'
              required:
                - email
                - password
    get:
      summary: Get user from token
      operationId: get-auth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
      description: "Get the data of a user based on his token, to re-authenticate him. Data includes the token.\n\n\U0001F510 Authentication"
      parameters: []
      tags:
        - Users
  /comments:
    get:
      summary: Get all comments
      tags:
        - Comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/comment'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: get-comments
      description: "Get all the comments made on every post.\n\n\U0001F510 Authentication - `USER_WRITE` permission\n\U0001F4DC Pagination - Max. 25 entities"
      parameters:
        - schema:
            type: string
          in: query
          name: search
          description: search for keywords in the content
        - schema:
            type: string
          in: query
          name: username
          description: search by author name
        - schema:
            type: string
          in: query
          name: email
          description: (only available with `USER_WRITE` permission) search by email
        - schema:
            type: string
          in: query
          name: ip
          description: (only available with `USER_WRITE` permission) search by IP address
  '/comments/{post_type}/{post_slug}':
    parameters:
      - schema:
          type: string
          enum:
            - publication
            - devblog
        name: post_type
        in: path
        required: true
      - schema:
          type: string
        name: post_slug
        in: path
        required: true
    get:
      summary: Get comments on a post
      tags:
        - Comments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/comment'
      operationId: get-comments-on-post
      description: "Get comments written on a post identified by its slug\n\n\U0001F4DC Pagination - Max. 25 entities"
      parameters:
        - schema:
            type: string
          in: query
          name: search
          description: search for keywords in the content
        - schema:
            type: string
          in: query
          name: username
          description: search by author name
        - schema:
            type: string
          in: query
          name: email
          description: (only available with `USER_WRITE` permission) search by email
        - schema:
            type: string
          in: query
          name: ip
          description: (only available with `USER_WRITE` permission) search by IP address
    post:
      summary: Submit a comment
      operationId: post-comments
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
      description: 'Submit, as a user, a comment on a post. Note that a moderator will have to validate the comment in order for it to be published.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: ''
                email:
                  type: string
                  description: ''
                content:
                  type: string
                  description: ''
              required:
                - username
                - email
                - content
      tags:
        - Comments
  /devblogs:
    get:
      summary: Get all devblogs
      tags:
        - Devblogs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/devblog'
      operationId: get-devblogs
      description: "Get all the publications. Returns a list of devblogs without the content.\n\n\U0001F4DC Pagination - Max. 10 entities"
      parameters:
        - schema:
            type: string
          in: query
          name: search
          description: search for devblogs (text inside title or content)
        - schema:
            type: string
          in: query
          name: category
          description: search by category
        - schema:
            type: string
          in: query
          name: author
          description: search for devblogs written by a specific author (using their username)
    post:
      summary: Create a devblog
      operationId: post-devblogs
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Write a new devblog and publish it.\n\n\U0001F510 Authentication - `DEVBLOG_WRITE` permission"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                category:
                  type: string
                illustration:
                  type: string
                content:
                  type: string
              required:
                - title
                - category
                - illustration
                - content
      tags:
        - Devblogs
  '/devblogs/{slug}':
    parameters:
      - schema:
          type: string
        name: slug
        in: path
        required: true
    get:
      summary: Get one devblog
      tags:
        - Devblogs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/devblog'
      operationId: get-devblogs-slug
      description: Get a single devblog based on its slug.
    delete:
      summary: Delete a devblog
      operationId: delete-devblogs-slug
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Permanently delete a devblog.\n\n\U0001F510 Authentication - `DEVBLOG_WRITE` permission"
      tags:
        - Devblogs
  '/publications/{slug}':
    parameters:
      - schema:
          type: string
        name: slug
        in: path
        required: true
    get:
      summary: Get one publication
      tags:
        - Publications
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/publication'
      operationId: get-publications-slug
      description: Get a single publication based on its slug.
    delete:
      summary: Delete a publication
      operationId: delete-publications-slug
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Permanently delete a publication.\n\n\U0001F510 Authentication - `BLOG_WRITE` permission"
      tags:
        - Publications
  '/comments/{post_type}/{post_slog}/{comment_slug}':
    parameters:
      - schema:
          type: string
        name: post_type
        in: path
        required: true
      - schema:
          type: string
        name: post_slog
        in: path
        required: true
      - schema:
          type: string
        name: comment_slug
        in: path
        required: true
    put:
      summary: Approve a comment
      operationId: approve-comment
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Approve a comment to make it publicly available.\n\n\U0001F510 Authentication - `USER_WRITE` permission"
      tags:
        - Comments
    delete:
      summary: Delete a comment
      operationId: delete-comment
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      description: "Permanently delete a comment, published or not.\n\n\U0001F510 Authentication - `USER_WRITE` permission"
      tags:
        - Comments
components:
  schemas:
    comment:
      title: Comment resource
      type: object
      description: 'Comments are made by readers on specific publications to give their opinion, suggest changes, give sources, interact with authors...'
      x-tags:
        - Comments
      properties:
        slug:
          type: string
          minLength: 2
          maxLength: 32
        username:
          type: string
          minLength: 2
          maxLength: 32
        email:
          type: string
          maxLength: 64
          minLength: 2
          format: email
        encoded_email:
          type: string
        ip:
          type: string
        post_type:
          type: string
          enum:
            - publication
            - devblog
        post:
          type: string
        content:
          type: string
          minLength: 1
          maxLength: 512
        is_validated:
          type: boolean
        pinned:
          type: boolean
        timestamp:
          type: integer
      required:
        - slug
        - username
        - email
        - encoded_email
        - ip
        - post_type
        - post
        - content
        - is_validated
        - pinned
        - timestamp
    user:
      type: object
      title: User resource
      description: 'Users are the central part of the API. They interact with content and, in some cases, create it.'
      properties:
        username:
          type: string
          description: 'username, is taken in the profile URL'
          minLength: 2
          maxLength: 32
        displayname:
          type: string
          description: '"pretty" name to display'
          minLength: 2
          maxLength: 32
        timestamp:
          type: integer
          description: 'unix timestamp, user creation'
        avatar:
          type: string
          description: URL of the user's profile picture
        description:
          type: string
          description: 'user''s description, markdown format'
          maxLength: 512
        biography:
          type: string
          description: 'user''s biography, used at the end of blog posts'
        location:
          type: string
          description: user's location (manually given by him)
          minLength: 0
          maxLength: 64
        socials:
          type: array
          description: user's social networks
          items:
            $ref: '#/components/schemas/social'
        is_email_public:
          type: boolean
          description: wether the user's email is public or private
        email:
          type: string
          description: 'user''s email, if set to public (see `is_email_public` field)'
          minLength: 2
          maxLength: 64
          format: email
      required:
        - username
        - displayname
        - timestamp
        - avatar
        - is_email_public
      x-tags:
        - Users
    social:
      title: Social component
      type: object
      x-tags:
        - Users
      description: Represents user's social network
      properties:
        name:
          type: string
          enum:
            - twitter
            - github
            - reddit
            - website
        value:
          type: string
      required:
        - name
        - value
    publication:
      title: Publication resource
      type: object
      description: 'Publications are created by redactors in the blog. They can be articles, tutorials and tips on various subjects such as informatic, development, etc...'
      x-tags:
        - Publications
      properties:
        slug:
          type: string
          description: 'post''s slug, serves as url'
        title:
          type: string
          description: post's title
        timestamp:
          type: integer
          description: 'unix timestamp, post creation'
        author:
          type: string
          description: author's username
        type:
          type: string
          description: post's type
          enum:
            - article
            - tutorial
            - news
        category:
          type: string
          description: 'post''s category, corresponding to the main theme : Apple, Web, hardware...'
          enum:
            - software
            - security
            - web
            - hardware
            - programming
            - android
            - linux
            - windows
            - apple
        description:
          type: string
          description: a summary of post's content
        keywords:
          description: labels for SEO
          type: array
          items:
            type: string
        illustration:
          type: string
          description: post's banner
          format: uri
        content:
          type: string
          description: |-
            post's content, mardown format.
            Is not included in a many-posts request
        locale:
          type: string
          description: post's locale
          enum:
            - fr
            - en
      required:
        - slug
        - title
        - timestamp
        - author
        - type
        - category
        - description
        - keywords
        - illustration
        - locale
    devblog:
      title: Devblog resource
      type: object
      description: 'Devblogs are created by BOP members and inform about the news around the team, the projects or anything else.'
      x-tags:
        - Devblogs
      properties:
        title:
          type: string
          description: post's title
        slug:
          type: string
          description: 'post''s slug, serving as url'
        category:
          type: string
          description: post's category
        illustration:
          type: string
          description: post's banner
          format: uri
        author:
          type: string
          description: author's username
        timestamp:
          type: integer
          description: "unix timestamp, post creation\t"
        content:
          type: string
          description: |-
            post's content, markdown format.
            Is not included in a many-posts request
      required:
        - title
        - slug
        - category
        - illustration
        - author
        - timestamp
  securitySchemes: {}
  responses:
    Error:
      description: Full error response when the HTTP code can't give enough details
      content:
        application/json:
          schema:
            type: object
            properties:
              key:
                type: string
                description: Error's unique identifier
              message:
                type: string
                description: Full text explanation of the error
            required:
              - key
              - message
  parameters:
    Authentication:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'User''s token, got through loging-in with an email and a password'
tags:
  - name: Comments
  - name: Devblogs
  - name: Publications
  - name: Users