From cd910e3074d6631e05d5a4dd52c3085f08303373 Mon Sep 17 00:00:00 2001 From: Aaron van Meerten Date: Mon, 14 Aug 2017 09:20:20 -0500 Subject: [PATCH] docs: document the services which jitsi meet can consume * new documentation for the services which jitsi meet can consume for conference mapping to dial-in numbers * attempted markdown link for swagger file from documentation file --- doc/cloud-api.md | 5 ++ doc/cloud-api.swagger | 147 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 doc/cloud-api.md create mode 100644 doc/cloud-api.swagger diff --git a/doc/cloud-api.md b/doc/cloud-api.md new file mode 100644 index 000000000..32c332dbc --- /dev/null +++ b/doc/cloud-api.md @@ -0,0 +1,5 @@ +# Jitsi Meet Cloud API + +The Jitsi Meet Cloud API is a specification for services which can support the integration of Jitsi Meet into other applications, for mapping conferences for dial-in support, and for supporting directory search and user invitations to conferences. + +The swagger for these services is provided in [cloud-api.swagger](cloud-api.swagger) in this same repository and directory. \ No newline at end of file diff --git a/doc/cloud-api.swagger b/doc/cloud-api.swagger new file mode 100644 index 000000000..269adb9a0 --- /dev/null +++ b/doc/cloud-api.swagger @@ -0,0 +1,147 @@ +swagger: "2.0" +info: + description: "Documents the REST calls used by Jitsi Meet to integrate with other services" + version: "1.0.0" + title: "Swagger Video" + termsOfService: "https://jitsi.org/CloudAPITOS/" + contact: + email: "team@jitsi.org" +host: "jitsi-api.jitsi.org" +basePath: "/" +tags: +- name: "conferenceMapper" + description: "Conference to ID Mapper" + externalDocs: + description: "Conference API Details" + url: "https://jitsi.org/CloudAPI" +- name: "phoneNumberList" + description: "List of dial-in numbers" +schemes: + - "https" +paths: + /conferenceMapper: + get: + tags: + - "conferenceMapper" + summary: "Create or retrieve conference ID mapping" + description: "When called with a conference, creates a new ID and both stores and returns the result. When called with an ID, returns the mapping if previously created." + operationId: "GETconferenceMapper" + consumes: + - "application/json" + produces: + - "application/json" + parameters: + - in: "query" + name: "conference" + type: "string" + format: "JID" + description: "Full JID (room@conference.server.domain) for the conference to create or return existing conference mapping. Used preferentially over all other input parameters (search by conference)" + - in: "query" + name: "id" + type: "number" + description: "ID to search for existing conference mapping. Only used when provided alone (search by ID)" + responses: + 200: + description: "mapping search performed" + schema: + $ref: "#/definitions/ConferenceMapperDetails" + 405: + description: "Invalid input" + post: + tags: + - "conferenceMapper" + summary: "Create or retrieve conference ID mapping" + description: "When called with a conference, creates a new ID and both stores and returns the result. When called with an ID, returns the mapping if previously created." + operationId: "POSTconferenceMapper" + consumes: + - "application/json" + produces: + - "application/json" + parameters: + - in: "body" + name: "body" + description: "Conference Mapper Request" + required: true + schema: + $ref: "#/definitions/ConferenceMapperRequest" + responses: + 200: + description: "mapping search performed" + schema: + $ref: "#/definitions/ConferenceMapperDetails" + 405: + description: "Invalid input" + + /phoneNumberList: + get: + tags: + - "phoneNumberList" + summary: "Returns a list phone numbers by country" + description: "Used to populate the Share The Link section of jitsi-meet" + operationId: "phoneNumberList" + produces: + - "application/json" + responses: + 200: + description: "successful operation" + schema: + $ref: "#/definitions/PhoneNumberList" +securityDefinitions: + token: + type: "apiKey" + name: "token" + in: "query" + Bearer: + type: "apiKey" + name: "Authorization" + in: "header" +definitions: + + ConferenceMapperRequest: + description: "Request to create or find a conference mapping" + type: "object" + properties: + id: + type: "number" + description: "ID to search for existing conference mapping. Only used when provided alone (search by ID)" + conference: + type: "string" + format: "JID" + description: "Full JID (room@conference.server.domain) for the conference to create or return existing conference mapping. Used preferentially over all other input parameters (search by conference)" + room: + type: "string" + description: "Room part of the conference. Required if 'conference' is not provided. Used to generate a 'conference' value (search by conference)" + domain: + type: "string" + description: "Domain part of the conference. Used if 'conference' is not provided. Defaults to domain of the API endpoint. Used to generate a 'conference' value (search by conference)" + + ConferenceMapperDetails: + description: "Conference mapping between conference JID and numeric ID" + type: "object" + properties: + id: + type: "number" + description: "Unique ID mapped to conference" + conference: + type: "string" + format: "JID" + description: "Full JID for the conference OR boolean false if no conference was found (search by ID)" + + PhoneNumberList: + type: "object" + properties: + numbersEnabled: + type: "boolean" + description: "Control flag for Jitsi Meet user interface. Must be set to true for Jitsi Meet to display phone-in UI elements" + numbers: + type: "object" + description: "Keys are Country Names, each value is an array of phone numbers" + additionalProperties: + type: "array" + items: + type: "string" + format: "phone" + +externalDocs: + description: "Find out more about the Jitsi Cloud API" + url: "https://jitsi.org/CloudAPI" \ No newline at end of file