openapi: 3.0.0 info: title: 'HAXcms API' description: 'API for interfacing with HAXcms end points' termsOfService: 'https://haxtheweb.org' contact: email: hax@psu.edu license: name: 'Apache 2.0' url: 'http://www.apache.org/licenses/LICENSE-2.0.html' version: servers: paths: /options: post: tags: - api operationId: 'Operations::options' responses: '200': description: 'API bandaid till we get all the APIs documented. This is an array of callbacks' /: post: tags: - api summary: 'Generate the swagger API documentation for this site' operationId: 'Operations::api' responses: '200': description: 'API documentation in YAML' /openapi/json: post: tags: - api summary: 'Generate the swagger API documentation for this site' operationId: 'Operations::openapi' responses: '200': description: 'API documentation in JSON' /saveManifest: post: tags: - cms - authenticated operationId: 'Operations::saveManifest' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Save the manifest of the site' /saveOutline: post: tags: - cms - authenticated - site operationId: 'Operations::saveOutline' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Save an entire site outline' /saveNode: post: tags: - cms - authenticated - node operationId: 'Operations::saveNode' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Save a node' /deleteNode: post: tags: - cms - authenticated - node operationId: 'Operations::deleteNode' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Delete a node' /siteUpdateAlternateFormats: post: tags: - cms - authenticated - meta operationId: 'Operations::siteUpdateAlternateFormats' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Update the alternative formats surrounding a site' /connectionSettings: get: tags: - cms operationId: 'Operations::connectionSettings' responses: '200': description: 'Generate the connection settings dynamically for implying we have a PHP backend' /generateAppStore: get: tags: - hax - api operationId: 'Operations::generateAppStore' parameters: - name: appstore_token in: query description: 'security token for appstore' required: true schema: type: string responses: '200': description: 'Generate the AppStore spec for HAX editor directions' /getUserData: post: tags: - cms - authenticated - user - settings operationId: 'Operations::getUserData' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Load data about the logged in user' /formLoad: post: tags: - cms - authenticated - form operationId: 'Operations::formLoad' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Load a form based on ID' /formProcess: post: tags: - cms - authenticated - form operationId: 'Operations::formProcess' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Process a form based on ID and input data' /listFiles: get: tags: - hax - authenticated - file operationId: 'Operations::listFiles' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string responses: '200': description: 'Load existing files for presentation in HAX find area' /login: post: tags: - cms - user description: 'Attempt a user login' operationId: 'Operations::login' parameters: - name: u in: query description: 'User name' required: true schema: type: string example: admin - name: p in: query description: Password required: true schema: type: string example: admin responses: '200': description: 'JWT token as response' '403': description: 'Invalid token / Login is required' /logout: post: tags: - cms - user operationId: 'Operations::logout' responses: '200': description: 'User logout, front end will kill token' /refreshAccessToken: post: tags: - cms - user operationId: 'Operations::refreshAccessToken' responses: '200': description: 'User access token for refreshing JWT when it goes stale' /saveFile: post: tags: - hax - authenticated - file operationId: 'Operations::saveFile' parameters: - name: site_token in: query description: 'Site-specific validation token' required: true schema: type: string - name: siteName in: query description: 'Name of the site to upload the file to' required: true schema: type: string - name: nodeId in: query description: 'ID of the node/page to associate the file with' required: true schema: type: string requestBody: content: multipart/form-data: schema: required: - file-upload properties: file-upload: type: string format: binary description: 'File to upload' type: object responses: '200': description: 'User is uploading a file to present in a site' '500': description: 'Error uploading file' /listSites: get: tags: - cms operationId: 'Operations::listSites' responses: '200': description: 'Load a list of all sites the user has created' /cloneSite: post: tags: - cms - authenticated - site operationId: 'Operations::cloneSite' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string requestBody: content: application/json: schema: required: - site properties: site: type: object type: object example: site: name: mynewsite responses: '200': description: 'Clone a site by copying and renaming the folder on file system' /downloadSite: post: tags: - cms - authenticated - site - meta operationId: 'Operations::downloadSite' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string requestBody: content: application/json: schema: required: - site properties: site: type: object type: object example: site: name: mynewsite responses: '200': description: 'Download the site folder as a zip file' /archiveSite: post: tags: - cms - authenticated - site operationId: 'Operations::archiveSite' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string requestBody: content: application/json: schema: required: - site properties: site: type: object type: object example: site: name: mynewsite responses: '200': description: 'Archive a site by moving it on the file system' /createSite: post: tags: - cms - authenticated - site operationId: 'Operations::createSite' parameters: - name: jwt in: query description: 'JSON Web token, obtain by using /login' required: true schema: type: string - name: user_token in: query description: 'User validation token' required: true schema: type: string requestBody: content: application/json: schema: required: - site - theme properties: site: type: object properties: name: type: string domain: type: string description: type: string theme: type: string theme: type: object properties: image: type: string icon: type: string hexCode: type: string cssVariable: type: string build: type: object properties: structure: type: string type: type: string items: type: array files: type: object token: type: string type: object example: site: name: mynewsite domain: '' description: 'My new site description' theme: learn-two-theme theme: image: 'assets/banner.jpg' icon: 'icons:web' hexCode: '#3f51b5' cssVariable: '--simple-colors-default-theme-light-blue-7' responses: '200': description: 'Create a new site' /createNode: post: tags: - cms - authenticated - node operationId: 'Operations::createNode' parameters: - name: site_token in: query description: 'Site-specific validation token' required: true schema: type: string requestBody: content: application/json: schema: required: - site - node properties: site: type: object properties: name: type: string node: type: object properties: id: type: string title: type: string location: type: string duplicate: type: string contents: type: string indent: type: number order: type: number parent: type: string description: type: string metadata: type: object items: type: array description: 'Array of items for bulk creation (e.g., from docx import)' type: object example: site: name: mysite node: id: null title: 'Cool post' location: null indent: null order: null parent: null description: 'An example description for the post' metadata: tags: 'metadata,can,be,whatever,you,want' other: stuff responses: '200': description: 'Create a new node/page in a site' tags: - name: hax description: 'Operations required for HAX editor to work' externalDocs: description: 'Find out more about hax editor integrations' url: 'https://haxtheweb.org/integrations/create-new-ones' - name: cms description: 'Operations for the CMS side' - name: site description: 'Operations for sites' - name: node description: 'Operations for individual nodes in a site' - name: file description: 'Operations for files related to CMS or HAX' - name: form description: 'Operations related to form submission or generation' - name: meta description: 'Operations related to metadata management or processes' - name: git description: 'Operations related to git / version control of the site' - name: user description: 'Operations for the user account / object' - name: api description: 'endpoint to generate the API or surrounding API callbacks' - name: settings description: 'Internal settings related to configuration of this HAXcms deployment' - name: authenticated description: 'Operations requiring authentication' externalDocs: description: 'HAXcms and all things HAX documentations' url: 'https://haxtheweb.org/'