Skip to content

Instantly share code, notes, and snippets.

@makr0
Created March 7, 2020 14:49
Show Gist options
  • Save makr0/1289cd6ea263a8606ef7dcb2cd52027b to your computer and use it in GitHub Desktop.
Save makr0/1289cd6ea263a8606ef7dcb2cd52027b to your computer and use it in GitHub Desktop.
Craftnote API descript in swagger-format
swagger: '2.0'
info:
title: Craftnote API
version: 0.2.1
description: 'An API to manage projects, files and users in Craftnote.'
contact:
name: myCraftnote Digital GmbH
email: th@craftnote.de
url: 'https://www.craftnote.de'
license:
name: proprietary
consumes:
- application/json
produces:
- application/json
host: 'europe-west1-craftnote-live.cloudfunctions.net'
basePath: /api/v1
schemes:
- https
securityDefinitions:
ApiKeyAuth:
type: apiKey
in: header
name: X-CN-API-Key
security:
- ApiKeyAuth: []
paths:
/company/employees:
get:
description: List employees of the company associated with the API key -- not yet implemented!
tags:
- Company Employees (draft)
parameters:
- in: query
name: offset
type: integer
description: The number of items to skip.
- in: query
name: limit
type: integer
description: The numbers of items to return (maximum 100).
responses:
'200':
description: List returned successfully
schema:
$ref: '#/definitions/EmployeesList'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Unable to authorize
schema:
$ref: '#/definitions/Error'
'415':
description: Invalid content type
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
post:
description: Invite employees -- not yet implemented!
tags:
- Company Employees (draft)
parameters:
- in: body
name: body
description: The employees to invite
required: true
schema:
$ref: '#/definitions/InviteEmployeesList'
responses:
'202':
description: Invites sent
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'415':
description: Invalid content type
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
/projects:
get:
description: List all projects for the authorized account
tags:
- Projects
parameters:
- in: query
name: offset
type: integer
description: The number of items to skip.
- in: query
name: limit
type: integer
description: The numbers of items to return (maximum 100).
responses:
'200':
description: List returned successfully
schema:
$ref: '#/definitions/ProjectsList'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Unable to authorize
schema:
$ref: '#/definitions/Error'
'415':
description: Invalid content type
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
post:
description: Create a new project/project folder
tags:
- Projects
parameters:
- in: body
name: body
description: The project details
required: true
schema:
$ref: '#/definitions/ChangeProject'
responses:
'200':
description: Project successfully created
schema:
$ref: '#/definitions/Project'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'415':
description: Invalid content type
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
'/projects/{projectId}':
parameters:
- name: projectId
in: path
required: true
description: The ID of the project
type: string
get:
description: Get a project -- not yet implemented!
tags:
- Projects
responses:
'200':
description: Project returned succesfully
schema:
$ref: '#/definitions/Project'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID was not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
patch:
description: Update a project -- not yet implemented!
tags:
- Projects
parameters:
- in: body
name: body
description: The project details
required: true
schema:
$ref: '#/definitions/ChangeProject'
responses:
'200':
description: List returned successfully
schema:
$ref: '#/definitions/FilesList'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID was not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/projects/{projectId}/deeplink':
parameters:
- name: projectId
in: path
required: true
description: The ID of the project.
type: string
get:
description: Get project deeplink
tags:
- Projects
responses:
'200':
description: Project deeplink returned succesfully
schema:
$ref: '#/definitions/Deeplink'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID was not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/projects/{projectId}/files':
parameters:
- name: projectId
in: path
required: true
description: The ID of the project.
type: string
get:
description: List all files of a project
tags:
- Project Files
parameters:
- in: query
name: offset
type: integer
description: The number of items to skip.
- in: query
name: limit
type: integer
description: The numbers of items to return (maximum 100).
responses:
'200':
description: List returned successfully
schema:
$ref: '#/definitions/FilesList'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID was not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
post:
description: Create a file/folder
tags:
- Project Files
consumes:
- multipart/form-data
produces:
- multipart/form-data
parameters:
- in: formData
name: type
type: string
description: 'The file type (folder, document, image)'
required: true
- in: formData
name: folderId
type: string
description: The folder ID of the file
- in: formData
name: data
type: file
description: The content data (required if type is not a folder)
- in: formData
name: name
type: string
description: The name of the file (or folder) to create. If omitted the file name will be used. Required for creating a folder
responses:
'200':
description: File created successfully
schema:
$ref: '#/definitions/File'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'403':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID or folder ID were not found
schema:
$ref: '#/definitions/Error'
'413':
description: File size exceeds server limits
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/projects/{projectId}/files/deeplink':
parameters:
- name: projectId
in: path
required: true
description: The ID of the project.
type: string
get:
description: Get deeplink to project files -- not yet implemented!
tags:
- Project Files
responses:
'200':
description: List returned successfully
schema:
$ref: '#/definitions/Deeplink'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID was not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/files/{fileId}':
parameters:
- name: fileId
in: path
required: true
description: The ID of the file.
type: string
get:
description: Get a file/folder
tags:
- Project Files
produces:
- application/json
- image/json
- image/png
- application/pdf
parameters:
- in: query
name: download
type: boolean
description: Whether to download this file. If selected the response will contain the file content instead of its meta data.
responses:
'200':
description: File returned successfully
schema:
$ref: '#/definitions/File'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access the project this file is associated with
schema:
$ref: '#/definitions/Error'
'404':
description: File ID was not found
schema:
$ref: '#/definitions/Error'
'413':
description: File size exceeds server limits
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
put:
description: Update a file/folder
tags:
- Project Files
consumes:
- multipart/form-data
produces:
- multipart/form-data
parameters:
- in: formData
name: folderId
type: string
description: The folder ID of the file
- in: formData
name: data
type: file
description: The content data
- in: formData
name: name
type: string
description: The name of the new file (or folder)
responses:
'200':
description: File updated successfully
schema:
$ref: '#/definitions/File'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access the project this file is associated with
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID or folder ID were not found
schema:
$ref: '#/definitions/Error'
'413':
description: File size exceeds server limits
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/projects/{projectId}/members':
parameters:
- name: projectId
in: path
required: true
description: The ID of the project.
type: string
get:
description: List all members of a project -- not yet implemented!
tags:
- Project Members (draft)
parameters:
- in: query
name: offset
type: integer
description: The number of items to skip.
- in: query
name: limit
type: integer
description: The numbers of items to return (maximum 100).
responses:
'200':
description: List returned successfully
schema:
$ref: '#/definitions/MembersList'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID was not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
post:
description: Add members to a project -- not yet implemented!
tags:
- Project Members (draft)
parameters:
- in: body
name: body
description: The members to add
required: true
schema:
$ref: '#/definitions/AddMembersList'
responses:
'200':
description: Members added successfully
schema:
$ref: '#/definitions/MembersList'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'403':
description: Not allowed to access this project ID or edit members
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID or folder ID were not found
schema:
$ref: '#/definitions/Error'
'413':
description: File size exceeds server limits
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
'/projects/{projectId}/members/{memberId}':
parameters:
- name: projectId
in: path
required: true
description: The ID of the project.
type: string
- name: memberId
in: path
required: true
description: The ID of the member.
type: string
patch:
description: Edit a member -- not yet implemented!
tags:
- Project Members (draft)
parameters:
- in: body
name: body
description: The member details to change
required: true
schema:
$ref: '#/definitions/ChangeMember'
responses:
'200':
description: Member changed succesfully
schema:
$ref: '#/definitions/Member'
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID or edit members
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID or member ID were not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
delete:
description: Remove a member from a project -- not yet implemented!
tags:
- Project Members (draft)
responses:
'204':
description: Member removed succesfully
'400':
description: Bad request
schema:
$ref: '#/definitions/Error'
'401':
description: Not allowed to access this project ID or edit members
schema:
$ref: '#/definitions/Error'
'404':
description: Project ID or member ID were not found
schema:
$ref: '#/definitions/Error'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
Error:
type: object
required:
- message
properties:
message:
type: string
description: A message describing the error
example: An error occured.
Contact:
type: object
required:
- name
properties:
name:
type: string
description: The name of the contact
example: Herr Maier
pattern: '^[a-zA-ZäÄöÖüÜß ]+([ -][a-zA-ZäÄöÖüÜß ]+)*$'
emails:
type: array
items:
type: string
description: The email of the contact
example:
- maier@test.de
- maier2@test.de
pattern: '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$'
phones:
type: array
items:
type: string
description: The phone of the contact
example:
- +49 711 21893732
- +49 711 21893733
pattern: '[0-9 +]+'
ChangeProject:
type: object
required:
- name
properties:
name:
type: string
description: Name of this project
example: Wasserrohrbruch
projectType:
type: string
description: The project type (folder|project)
example: folder
orderNumber:
type: string
description: An arbitrary order number
example: 92a032as4.853-af62
street:
type: string
description: The street address of this project
example: Manteuffelstr. 40
zipcode:
type: string
description: ZIP code of this project
example: '12345'
city:
type: string
description: Name of the city of this project
example: Berlin
country:
type: string
description: Name of the country
example: Germany
billingName:
type: string
description: The name of the billing contact
example: Hornberger
billingStreet:
type: string
description: The street and address number of the billing conctact
example: Manteuffelstr. 40
billingZipcode:
type: string
description: ZIP code of the billing contact
example: '12345'
billingCity:
type: string
description: The city of the billing contact
example: Berlin
billingEmail:
type: string
description: The e-mail address of the billing contact
example: foo@bar.com
contacts:
type: array
items:
$ref: '#/definitions/Contact'
description: Contacts for this project
parentProject:
type: string
description: The ID of the parent project
example: db5b9a4d-7589-4af4-8c79-a96a3b796dc9
Project:
type: object
required:
- name
properties:
id:
type: string
description: Unique project ID
example: 0000FFB2-9DC1-4A50-A8BB-14C899CC52FC
name:
type: string
description: Name of this project
example: Wasserrohrbruch
projectType:
type: string
description: The project type (FOLDER|PROJECT)
example: FOLDER
orderNumber:
type: string
description: Order number for this project
example: 12312344d
street:
type: string
description: The street address of this project
example: Manteuffelstr. 40
zipcode:
type: string
description: ZIP code of this project
example: '12345'
city:
type: string
description: Name of the city of this project
example: Berlin
county:
type: string
description: Name of the country
example: Germany
billingName:
type: string
description: The name of the billing contact
example: Hornberger
billingEmail:
type: string
description: The e-mail address of the billing contact
example: foo@bar.com
billingStreet:
type: string
description: The street and address number of the billing conctact
example: Manteuffelstr. 40
billingCity:
type: string
description: The city of the billing contact
example: Berlin
contacts:
type: array
items:
$ref: '#/definitions/Contact'
description: Contacts for this project
projects:
type: array
description: IDs of projects contained in this project (only applies to type folder)
items:
type: string
ProjectsList:
type: object
required:
- projects
properties:
projects:
type: array
items:
$ref: '#/definitions/Project'
Deeplink:
type: object
required:
- webLink
- appDeepLink
properties:
webLink:
type: string
description: A link that can be opened in a browser
example: 'https://app.mycraftnote.de/#/project?id=0DDAAAA9-2508-4AAF-A576-E91E76EA8CDB'
appDeepLink:
type: string
description: A link that can be opened in a mobile client
example: 'mycrafty://project?id=0DDAAAA9-2508-4AAF-A576-E91E76EA8CDB'
File:
type: object
required:
- id
- name
- type
properties:
id:
type: string
description: The unique ID of the file
example: 00061E3C-9C02-3CE5-EDFD-9186E6F28114
projectId:
type: string
description: The project ID of this file
example: db5b9a4d-7589-4af4-8c79-a96a3b796dc9
name:
type: string
description: The user-defined file name
example: Projektbericht.pdf
folderId:
type: string
description: The parent folder ID of this file
example: 00061E3C-9C02-3CE5-EDFD-9186E6F28114
type:
type: string
description: 'The file type (FOLDER, DOCUMENT, IMAGE, AUDIO, VIDEO)'
example: DOCUMENT
creationTimestamp:
type: string
description: The creation timestamp as UNIX date
example: 1567685998
size:
type: number
description: The file size in bytes
example: 2450
FilesList:
type: object
required:
- files
properties:
files:
type: array
items:
$ref: '#/definitions/File'
Member:
type: object
properties:
id:
type: string
description: The unique ID of the member
example: Ka3gh32ashtQJuuas9
email:
type: string
description: The e-mail address of the member
example: cf@gauss.de
name:
type: string
description: The name of this member
example: Carl-Friedrich
lastname:
type: string
description: The last name of this member
example: Gauss
role:
type: string
description: The role this member has in a project
example: OWNER
MembersList:
type: object
required:
- members
properties:
members:
type: array
items:
$ref: '#/definitions/Member'
AddMember:
type: object
required:
- id
- role
properties:
id:
type: string
description: The unique ID of the member
example: Ka3gh32ashtQJuuas9
role:
type: string
description: The role this member has in a project
example: OWNER
AddMembersList:
type: object
required:
- members
properties:
members:
type: array
items:
$ref: '#/definitions/AddMember'
ChangeMember:
type: object
required:
- role
properties:
role:
type: string
description: The role this member has in a project
example: OWNER
Employee:
type: object
properties:
id:
type: string
description: The unique ID of the employee
example: Ka3gh32ashtQJuuas9
email:
type: string
description: The e-mail address of the employee
example: cf@gauss.de
name:
type: string
description: The name of this employee
example: Carl-Friedrich
lastname:
type: string
description: The last name of this employee
example: Gauss
jobTitle:
type: string
description: The job title of this employee
example: Mathematician
EmployeesList:
type: object
required:
- members
properties:
members:
type: array
items:
$ref: '#/definitions/Employee'
InviteEmployee:
type: object
properties:
id:
type: string
description: The unique ID of this employee
example: Ka3gh32ashtQJuuas9
email:
type: string
description: The e-mail address
example: cf@gauss.de
phone:
type: string
description: The phone number
example: 49171199132
InviteEmployeesList:
type: object
required:
- members
properties:
members:
type: array
items:
$ref: '#/definitions/InviteEmployeesList'
@Woersty
Copy link

Woersty commented Mar 7, 2020

😃 Geht! Eben gestestet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment