Last active
May 4, 2016 20:10
-
-
Save bsavage/c33469c10f32a7b3724c to your computer and use it in GitHub Desktop.
VOOT2 protocol expressed as swagger2 json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "swagger": "2.0", | |
| "info": { | |
| "version": "2.0.0", | |
| "title": "VOOT version 2" | |
| }, | |
| "host": "voot-provider.example.org", | |
| "basePath": "/v2", | |
| "schemes": [ | |
| "http", | |
| "https" | |
| ], | |
| "consumes": [ | |
| "application/json" | |
| ], | |
| "produces": [ | |
| "application/json" | |
| ], | |
| "securityDefinitions": { | |
| "oauth": { | |
| "type": "oauth2", | |
| "flow": "implicit", | |
| "authorizationUrl": "https://voot-provider.example.org/oauth/authorize/?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token", | |
| "scopes": { | |
| "general": "To read any and all group data provided by voot2 api." | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ], | |
| "paths": { | |
| "/groups": { | |
| "get": { | |
| "summary": "Group information", | |
| "description": "The groups endpoint returns lists of groups associated with the current authentication user (token) - active, expired and inactive. The response includes a unique id for each group and a display name. An empty list is returned if there are no groups for the authenticated user.", | |
| "parameters": [ | |
| { | |
| "name": "query", | |
| "in": "query", | |
| "description": "Match terms for start of display name.", | |
| "required": false, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "An array of group ids and their associated display names", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Group" | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/groups/{groupid}": { | |
| "get": { | |
| "description": "Details about a group that the authenticated user has access to. The user may retrieve group information for groups even if the user is not a member (for example, a public group).", | |
| "parameters": [ | |
| { | |
| "name": "groupid", | |
| "in": "path", | |
| "description": "Id of the group", | |
| "required": true, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Details about the group associated with the specified id", | |
| "schema": { | |
| "$ref": "#/definitions/Group" | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/groups/{groupid}/members": { | |
| "get": { | |
| "description": "Gets all **active** members of the group specified by groupid provided the authenticated user has access. Expired of otherwise inative members will not be returned by default. An empty list is returned if there are no members.", | |
| "parameters": [ | |
| { | |
| "name": "groupid", | |
| "in": "path", | |
| "description": "Id of the group", | |
| "required": true, | |
| "type": "string" | |
| }, | |
| { | |
| "name": "showAll", | |
| "in": "query", | |
| "description": "Directs provider to list all members of group including expired and inactive user memberships.", | |
| "required": false, | |
| "type": "boolean" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "An array of members associated with the specified group id", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Membership" | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/grouptypes": { | |
| "get": { | |
| "summary": "Group types", | |
| "description": "The grouptypes endpoint returns a list of groups types. The response includes the unique type id and display name. An empty list is returned if no group types are found.", | |
| "responses": { | |
| "200": { | |
| "description": "An array of group types ids and their associated display names.", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Group" | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/me/groups": { | |
| "get": { | |
| "summary": "Group membership of current user", | |
| "description": "This endpoint returns a list of **active** groups memberships of the current user. By defaul, expired or otherwise inactive groups are not returned. The response includes membership information including roles. An empty list is returned if there are no groups for the authenticated user.", | |
| "parameters": [ | |
| { | |
| "name": "showAll", | |
| "in": "query", | |
| "description": "Directs provider to list all groups the current authenticated user is associated with including expired and inactive user memberships.", | |
| "required": false, | |
| "type": "boolean" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "An array of group ids and their associated display names", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/GroupMemberships" | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ] | |
| } | |
| }, | |
| "/me/groups/{groupid}": { | |
| "get": { | |
| "summary": "Relationship of current user to group specified", | |
| "description": "This endpoint returns the authenticated user's relationship to the specified group (via groupid parameter). The user's relationship and display name for that relationship are returned.", | |
| "parameters": [ | |
| { | |
| "name": "groupid", | |
| "in": "path", | |
| "description": "Id of the group", | |
| "required": true, | |
| "type": "string" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "User's relationship to group and its associated display name.", | |
| "schema": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/Relationship" | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "oauth": [ | |
| "general" | |
| ] | |
| } | |
| ] | |
| } | |
| } | |
| }, | |
| "definitions": { | |
| "Group": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "description": "Unique idenfier for the group", | |
| "type": "string" | |
| }, | |
| "displayName": { | |
| "description": "Literal name of group", | |
| "type": "string" | |
| } | |
| } | |
| }, | |
| "Membership": { | |
| "type": "object", | |
| "properties": { | |
| "name": { | |
| "description": "Member name", | |
| "type": "string" | |
| }, | |
| "email": { | |
| "description": "Member email", | |
| "type": "string" | |
| }, | |
| "profilePhotoURL": { | |
| "description": "Full URL that resolved to member photo", | |
| "type": "string" | |
| }, | |
| "membership": { | |
| "description": "Type of membership", | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/definitions/MembershipType" | |
| } | |
| } | |
| } | |
| }, | |
| "MembershipType": { | |
| "type": "string", | |
| "properties": { | |
| "basic": { | |
| "description": "Category of basic membership", | |
| "type": "string" | |
| } | |
| } | |
| }, | |
| "Relationship": { | |
| "properties": { | |
| "name": { | |
| "$ref": "#/definitions/MembershipType" | |
| }, | |
| "displayName": { | |
| "description": "Display name of member relationship", | |
| "type": "string" | |
| } | |
| } | |
| }, | |
| "GroupMemberships": { | |
| "type": "object", | |
| "properties": { | |
| "group": { | |
| "$ref": "#/definitions/Group" | |
| }, | |
| "relationship": { | |
| "$ref": "#/definitions/Relationship" | |
| }, | |
| "active": { | |
| "description": "Active or inactive status", | |
| "type": "string" | |
| }, | |
| "notBefore": { | |
| "description": "Time constraint on membership in ISO 8601 combined data and time form (e.g., 2006-08-01T12:00:00Z)", | |
| "type": "string" | |
| }, | |
| "public": { | |
| "description": "True if group is public, false otherwise", | |
| "type": "boolean" | |
| }, | |
| "sourceID": { | |
| "description": "Source of group information", | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment