253 lines
8 KiB
YAML
253 lines
8 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
version: v0.0.0
|
|
title: Guichet API v0
|
|
description: |
|
|
Programmatic API for managing a user account in Deuxfleurs' Guichet.
|
|
|
|
*Disclaimer: this API is currently unstable and does not yet cover all the features availble from Guichet's web interface.*
|
|
|
|
paths:
|
|
/website:
|
|
get:
|
|
tags:
|
|
- Website
|
|
operationId: "ListWebsites"
|
|
summary: "List all websites"
|
|
description: |
|
|
List all the user's websites.
|
|
|
|
Also includes information about global quotas for the user, and for each website, bucket names and website URL.
|
|
|
|
- `username`: the name of the user making the request.
|
|
- `quota_website_count` indicates the quota of the number of websites that the user is allowed to create.
|
|
|
|
- Website size is set at 100MB by default, and users can increase this quota autonomously up to a certain value defined by `burst_bucket_quota_size`, by default it's set to 200MB but it can be overriden on a per-user basis.
|
|
|
|
- Each element of the `vhosts` array describes a website. A website is described by:
|
|
+ `name`: current main name of the website, which determines the URL it can be accessed from (specified in `domain`). This is also a name of the S3 bucket storing the website.
|
|
+ `alt_name`: an array of aliases for the website. These can also be used to access the S3 bucket storing the website (a bucket can have several aliased names), but cannot be used in a URL to access the website.
|
|
+ `expanded`: whether the bucket name already corresponds to a full URL for the website
|
|
+ `domain`: the URL at which the website can be reached
|
|
|
|
responses:
|
|
'500':
|
|
description: |
|
|
The server can not answer your request because it is in a bad state
|
|
'200':
|
|
description: |
|
|
Returns information about all the user's websites, and user information related to websites.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
example: "user"
|
|
quota_website_count:
|
|
$ref: '#/components/schemas/Quota'
|
|
burst_bucket_quota_size:
|
|
type: string # TODO: improve?
|
|
example: "200 Mio"
|
|
vhosts:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Vhost'
|
|
|
|
/website/{vhost}:
|
|
parameters:
|
|
- name: vhost
|
|
in: path
|
|
description: "Website identifier"
|
|
required: true
|
|
schema:
|
|
type: string
|
|
style: simple
|
|
get:
|
|
tags:
|
|
- Website
|
|
operationId: "GetWebsite"
|
|
summary: "Details on a website"
|
|
description: |
|
|
Gets the configuration and status for the website `vhost`.
|
|
This includes information about bucket names, domains, bucket access keys, and quotas.
|
|
|
|
- `vhost` contains informations about bucket names and the website URL. See the documentation of the response of "List all websites" for more information
|
|
- `access_key_id`: the S3 access key id for the bucket
|
|
- `secret_access_key`: the S3 secret access key for the bucket
|
|
- `quota_size`: the quota for the size of the website, in bytes.
|
|
- `quota_files`: the quota for the number of files.
|
|
responses:
|
|
'500':
|
|
description: |
|
|
The server can not answer your request because it is in a bad state
|
|
'404':
|
|
description: |
|
|
Website not found
|
|
'200':
|
|
description: |
|
|
Returns information about the website.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WebsiteInfo'
|
|
|
|
post:
|
|
tags:
|
|
- Website
|
|
operationId: "CreateWebsite"
|
|
summary: "Create a new website"
|
|
description: |
|
|
Creates a new website with identifier `vhost`.
|
|
|
|
responses:
|
|
'500':
|
|
description: |
|
|
The server can not answer your request because it is in a bad state
|
|
'400':
|
|
description: |
|
|
Your request is malformed, `vhost` must be non-empty.
|
|
'403':
|
|
description: |
|
|
Request forbidden, you have reached your quota of maximum number of websites allowed.
|
|
'200':
|
|
description: |
|
|
Returns information about the website that has been created. (See the documentation of "Details on a website" for more info.)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WebsiteInfo'
|
|
|
|
patch:
|
|
tags:
|
|
- Website
|
|
operationId: "ConfigureWebsite"
|
|
summary: "Configure website"
|
|
description: |
|
|
Modifies configuration of the website with identifier `vhost`.
|
|
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
quota_size:
|
|
type: integer
|
|
format: int64
|
|
nullable: true
|
|
example: null
|
|
vhost:
|
|
type: string
|
|
nullable: true
|
|
example: "my-website"
|
|
rotate_key:
|
|
type: boolean
|
|
nullable: true
|
|
example: true
|
|
|
|
responses:
|
|
'500':
|
|
description: |
|
|
The server can not answer your request because it is in a bad state
|
|
'400':
|
|
description: |
|
|
Your request is malformed, check your JSON
|
|
'404':
|
|
description: |
|
|
Website not found
|
|
'200':
|
|
description: |
|
|
Returns updated information about the website. (See the documentation of "Details on a website" for more info.)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WebsiteInfo'
|
|
|
|
delete:
|
|
tags:
|
|
- Website
|
|
operationId: "DeleteWebsite"
|
|
summary: "Delete Website"
|
|
description: |
|
|
Delete the website with identifier `vhost`.
|
|
|
|
responses:
|
|
'500':
|
|
description: |
|
|
The server can not answer your request because it is in a bad state
|
|
'400':
|
|
description: |
|
|
Bad request, empty website identifier or website has unfinished uploads
|
|
'404':
|
|
description: |
|
|
Website not found
|
|
'204':
|
|
description: |
|
|
Success
|
|
|
|
components:
|
|
securitySchemes:
|
|
basicAuth:
|
|
type: http
|
|
scheme: basic
|
|
schemas:
|
|
WebsiteInfo:
|
|
type: object
|
|
properties:
|
|
vhost:
|
|
$ref: '#/components/schemas/Vhost'
|
|
access_key_id:
|
|
type: string
|
|
example: "GK31c2f218a2e44f485b94239e"
|
|
secret_access_key:
|
|
type: string
|
|
example: "b892c0665f0ada8a4755dae98baa3b133590e11dae3bcc1f9d769d67f16c3835"
|
|
quota_size:
|
|
$ref: '#/components/schemas/Quota'
|
|
quota_files:
|
|
$ref: '#/components/schemas/Quota'
|
|
Vhost:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: "my-website"
|
|
alt_name:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: "my-other-website-name"
|
|
expanded:
|
|
type: boolean
|
|
example: false
|
|
domain:
|
|
type: string
|
|
example: "my-website.web.deuxfleurs.fr"
|
|
Quota:
|
|
type: object
|
|
properties:
|
|
current:
|
|
type: integer
|
|
format: int64
|
|
example: 1000
|
|
max:
|
|
type: integer
|
|
format: int64
|
|
example: 5000
|
|
ratio:
|
|
type: number
|
|
format: double
|
|
example: 0.2
|
|
burstable:
|
|
type: boolean
|
|
example: true
|
|
|
|
security:
|
|
- basicAuth: []
|
|
|
|
servers:
|
|
- description: Guichet Deuxfleurs
|
|
url: https://guichet.deuxfleurs.fr/api/v0/
|