ACL Management API prototype

README.md

Open it in a fancy viewer here or locally with swagger-local:

$ swagger-local swagger.yaml

swagger.yaml

---
swagger: "2.0"
info:
  title: PermissionManager-${ENVIRONMENT}
  description: An API to manage permissions. Meant to be combined with [restricted](https://npmjs.com/package/restricted) in front- and back-end.
  contact:
    name: Joakim Hedlund
    email: contact@joakimhedlund.com
  version: 0.0.1
schemes:
  - https
basePath: /v1

tags:
- name: "permissions"
  description: "Manage scope definitions"
- name: "groups"
  description: "Manage predefined ACL configurations"
- name: "users"
  description: "Assign users to groups or direct permissions"

definitions:
  PermissionScope:
    type: object
    properties:
      scope:
        type: string
        description: E.g. `comments.write`
      description:
        type: string
        description: An optional summary of what the permission means.
      createdAt:
        type: string
        format: date-time
      updatedAt:
        type: string
        format: date-time
  PermissionScopeSet:
    type: object
    properties:
      scopes:
        type: array
        items:
          $ref: '#/definitions/PermissionScope'
  PermissionCollection:
    description: An arbitrary grouping of permissions. Joins a set of functionalities together, such as permissions related to Comments
    type: object
    properties:
      name:
        type: string
      scopes:
        type: array
        description: List of Permissions that are included in the group.
        items:
          $ref: '#/definitions/PermissionScope'
  UserPermission:
    type: object
    required:
      - userId
      - scope
      - action
    properties:
      userId:
        type: string
        description: The user for which to apply the permission.
      scope:
        type: string
        description: Which permission to set a value for.
      action:
        type: string
        description: One of `"allow"`, `"disallow"` or `"forget"` (inherit).
      createdAt:
        type: string
        format: date-time
      updatedAt:
        type: string
        format: date-time

x-definitions:
  200Response: &200Response
    description: Success

paths:
  /users/{userId}/permissions:
    get:
      summary: Retrieve all stored permissions for a user.
      tags:
      - users
      parameters:
        - name: userId
          in: path
          type: string
          required: true
      responses:
        200:
          <<: *200Response
          description: All stored permissions for the user.
          schema:
            $ref: '#/definitions/PermissionScopeSet'
    post:
      summary: Insert or update a batch of permission scopes for a user.
      tags:
      - users
      parameters:
        - name: userId
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            $ref: '#/definitions/PermissionScopeSet'
      responses:
        200:
          <<: *200Response
          description: All stored permissions for the user.
          schema:
            $ref: '#/definitions/PermissionScopeSet'

  /permissions/scopes:
    get:
      summary: List all predefined scopes.
      tags:
      - permissions
      responses:
        200:
          <<: *200Response
          schema:
            $ref: '#/definitions/PermissionScopeSet'
  
  /permissions/scopes/{scope}:
    post:
      summary: Insert or update the definition for a permission scope.
      tags:
      - permissions
      parameters:
        - name: scope
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            $ref: '#/definitions/PermissionScope'
      responses:
        200:
          <<: *200Response
          schema:
            $ref: '#/definitions/PermissionScope'

  /permissions/collections:
    get:
      summary: List predefined scopes, grouped by scope collection.
      tags:
      - permissions
      responses:
        200:
          <<: *200Response
          schema:
            type: object
            properties:
              collections:
                type: array
                items:
                  $ref: '#/definitions/PermissionCollection'