diff --git a/Makefile b/Makefile index d804c27a4..b8ff1204f 100644 --- a/Makefile +++ b/Makefile @@ -103,6 +103,11 @@ makemessages: cd $(srcDir) && $(PYTHON) manage.py makemessages -d djangojs -l fr -l es -l pt --symlinks --no-wrap +generateschema: + cd $(srcDir) && $(PYTHON) manage.py generateschema --url http://cowork.djaoapp.com > schema.yml + cd $(srcDir) && swagger-cli validate schema.yml + + migratedb-cowork: initdb-cowork @echo "-- Set streetside processor deposit key." $(SQLITE) $(call MULTITIER_DB_NAME) "UPDATE saas_organization set processor_deposit_key='$(shell grep ^STRIPE_TEST_CONNECTED_KEY $(CONFIG_DIR)/credentials | cut -f 2 -d \")' where is_provider=1;" diff --git a/djaoapp/api/custom_themes.py b/djaoapp/api/custom_themes.py index 1471ab1de..0c97a2403 100644 --- a/djaoapp/api/custom_themes.py +++ b/djaoapp/api/custom_themes.py @@ -19,4 +19,30 @@ def theme(self): class AppUpdateAPIView(RulesAppUpdateAPIView): + """ + Returns the URL endpoint to which requests passing the access rules + are forwarded to, and the format in which the session information + is encoded. + + When running tests, you can retrieve the actual session information + for a specific user through the `/proxy/sessions/{user}/` API call. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "slug": "cowork", + "entry_point": "http://localhost:8001/", + "session_backend": 1 + } + """ serializer_class = AppSerializer diff --git a/djaoapp/api/notifications.py b/djaoapp/api/notifications.py index 530c22b26..c38ffb606 100644 --- a/djaoapp/api/notifications.py +++ b/djaoapp/api/notifications.py @@ -96,6 +96,13 @@ def post(self, request, *args, **kwargs):#pylint:disable=unused-argument POST /api/notifications/contact_requested_notice/ HTTP/1.1 + responds + + .. code-block:: json + + { + "details": "Test email sent to xia@example.com" + } """ try: app = get_current_app() diff --git a/djaoapp/api/organizations.py b/djaoapp/api/organizations.py index 0a76c1098..74d56ec06 100644 --- a/djaoapp/api/organizations.py +++ b/djaoapp/api/organizations.py @@ -38,6 +38,18 @@ class OrganizationDetailAPIView(OrganizationDetailBaseAPIView): "full_name": "Xia Lee", "printable_name": "Xia Lee", "slug": "xia", + "phone": "555-555-5555", + "street_address": "185 Berry St #550", + "locality": "San Francisco", + "region": "CA", + "postal_code": "", + "country": "US", + "default_timezone": "Europe/Kiev", + "is_provider": false, + "is_bulk_buyer": false, + "type": "", + "picture": "", + "extra": "", "subscriptions": [ { "created_at": "2018-01-01T00:00:00Z", @@ -63,6 +75,8 @@ def put(self, request, *args, **kwargs): PUT /api/profile/xia/ HTTP/1.1 + responds + .. code-block:: json { diff --git a/djaoapp/api/roles.py b/djaoapp/api/roles.py index 4ab4a0d84..77f3e1fd6 100644 --- a/djaoapp/api/roles.py +++ b/djaoapp/api/roles.py @@ -57,7 +57,7 @@ class RoleListAPIView(RoleListBaseAPIView): }, "request_key": "1", "grant_key": null - }, + } ] } """ diff --git a/djaoapp/api/users.py b/djaoapp/api/users.py index e13513f84..a8868b000 100644 --- a/djaoapp/api/users.py +++ b/djaoapp/api/users.py @@ -7,7 +7,7 @@ from django.contrib.auth import get_user_model from django.utils.translation import ugettext_lazy as _ -from rest_framework.generics import GenericAPIView +from rest_framework.generics import ListAPIView from rest_framework.response import Response from saas.models import Charge @@ -37,9 +37,9 @@ class UserProfileAPIView(UserProfileBaseAPIView): .. code-block:: json { - "username": "donny", - "email": "donny.smith@example.com" - "full_name": "Donny Smith" + "username": "donny", + "email": "donny.smith@locahost.localdomain", + "full_name": "Donny Smith" } """ def perform_destroy(self, instance): @@ -52,10 +52,39 @@ def perform_destroy(self, instance): super(UserProfileAPIView, self).perform_destroy(instance) -class RecentActivityAPIView(GenericAPIView): +class RecentActivityAPIView(ListAPIView): + """ + Retrieves recently active users + + **Tags: metrics + + **Example + + .. code-block:: http + + GET /api/proxy/recent/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "printable_name": "Alice Cooper", + "descr": "recently logged in", + "created_at": "2019-07-15T20:40:29.509572Z", + "slug": "alice" + } + ] + } + """ serializer_class = ActivitySerializer - def get(self, request, *args, **kwargs): + def get_queryset(self): start_at = day_periods()[0] users = get_user_model().objects.filter( last_login__gt=start_at).order_by('-last_login')[:5] @@ -79,5 +108,4 @@ def get(self, request, *args, **kwargs): # TODO 404 for some of the slugs 'slug': charge.customer.slug} data = sorted(data.values(), key=itemgetter('printable_name')) - return Response({'results': - self.get_serializer(data, many=True).data}) + return data diff --git a/djaoapp/management/commands/generate_api_examples.py b/djaoapp/management/commands/generate_api_examples.py index 30dd8bf7b..3ea497e45 100644 --- a/djaoapp/management/commands/generate_api_examples.py +++ b/djaoapp/management/commands/generate_api_examples.py @@ -2,6 +2,7 @@ # see LICENSE import json, logging, re +from hashlib import sha256 from django.conf import settings from django.core.management.base import BaseCommand @@ -23,19 +24,46 @@ def add_arguments(self, parser): parser.add_argument('--provider', action='store', dest='provider', default=settings.APP_NAME, help='create sample subscribers on this provider') + parser.add_argument('--errors', action='store_true', default=False, + help='toggle errors') def handle(self, *args, **options): formatted_examples = [] - api_base_url = getattr(settings, 'API_BASE_URL', '/api') + api_base_url = getattr(settings, + 'API_BASE_URL', 'https://djaodjin.com/api') generator = APIDocGenerator(info=OPENAPI_INFO, url=api_base_url) schema = generator.get_schema(request=None, public=True) + descr_hashes = [] for path, path_details in schema.paths.items(): for func, func_details in path_details.items(): try: func_tags, summary, description, examples = \ split_descr_and_examples(func_details, api_base_url=api_base_url) - formatted_examples += format_examples(examples) + func_examples = format_examples(examples) + hsh = sha256(func_details.description.encode()).hexdigest() + errors = [] + if func_examples[0]['path']: + if ('responds' not in examples and func != 'DELETE'): + errors.append('missing-response') + else: + func_examples[0]['path'] = path + func_examples[0]['func'] = func + if not description and not examples: + errors.append('undocumented') + else: + errors.append('parsing') + if hsh in descr_hashes: + errors.append('duplicate-description') + else: + descr_hashes.append(hsh) + if options['errors']: + if errors: + func_examples[0]['errors'] = errors + formatted_examples += func_examples + else: + if not errors: + formatted_examples += func_examples except AttributeError: pass self.stdout.write(json.dumps(formatted_examples, indent=2)) diff --git a/djaoapp/templates/docs/api.html b/djaoapp/templates/docs/api.html index 608198509..6b261287a 100644 --- a/djaoapp/templates/docs/api.html +++ b/djaoapp/templates/docs/api.html @@ -165,9 +165,8 @@

{{api_end_point.summary}}

- 
-{{api_end_point.func|upper}} {{api_end_point.path}}
-
+ 
+{{api_end_point.func|upper}} {{api_end_point.path}}
{{api_end_point.description}}
diff --git a/djaoapp/views/docs.py b/djaoapp/views/docs.py index 8ce9b810d..ecb04045f 100644 --- a/djaoapp/views/docs.py +++ b/djaoapp/views/docs.py @@ -151,8 +151,9 @@ def format_examples(examples): # in_respoonse IN_URL_STATE = 0 IN_REQUEST_PARAMS_STATE = 1 - IN_RESPONSE_STATE = 2 - IN_RESPONSE_EXAMPLE_STATE = 3 + IN_REQUEST_PARAMS_EXAMPLE_STATE = 2 + IN_RESPONSE_STATE = 3 + IN_RESPONSE_EXAMPLE_STATE = 4 formatted_examples = [] state = IN_URL_STATE @@ -162,7 +163,7 @@ def format_examples(examples): resp = "" for line in examples.splitlines(): line = line.strip() - look = re.match(r'(GET|POST|PUT|PATCH)\s+(\S+)\s+HTTP', line) + look = re.match(r'(GET|POST|PUT|PATCH|DELETE)\s+(\S+)\s+HTTP', line) if look: func = look.group(1) path = look.group(2) @@ -176,13 +177,21 @@ def format_examples(examples): continue look = re.match('.. code-block::', line) if look: + if state == IN_REQUEST_PARAMS_STATE: + state = IN_REQUEST_PARAMS_EXAMPLE_STATE if state == IN_RESPONSE_STATE: state = IN_RESPONSE_EXAMPLE_STATE continue - if state == IN_REQUEST_PARAMS_STATE: - request_params += line + if state == IN_REQUEST_PARAMS_EXAMPLE_STATE: + if not request_params or line.strip(): + request_params += line + else: + state = IN_REQUEST_PARAMS_STATE elif state == IN_RESPONSE_EXAMPLE_STATE: - resp += line + if not resp or line.strip(): + resp += line + else: + state = IN_RESPONSE_STATE formatted_example = {'func': func, 'path': path} if request_params: try: @@ -256,7 +265,7 @@ def split_descr_and_examples(func_details, api_base_url=None): in_examples = True sep = "" elif in_examples: - for method in ('GET', 'POST', 'PUT', 'PATCH'): + for method in ('GET', 'POST', 'PUT', 'PATCH', 'DELETE'): look = re.match(r'.* (%s /api)' % method, line) if look: line = line.replace(look.group(1), diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 000000000..a47832136 --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,11662 @@ +openapi: 3.0.0 +info: + title: DjaoApp API + description: API to deploy apps on the djaodjin platform + termsOfService: https://djaodjin.com/legal/terms-of-use/ + contact: + email: test@example.com + license: + name: BSD License + version: v1 +security: + - basic: [] +paths: + /accounts/: + get: + operationId: accounts_list + description: >- + Queries a page (``PAGE_SIZE`` records) of organization and user + profiles. + + + The queryset can be filtered for at least one field to match a search + + term (``q``). + + + The queryset can be ordered by a field by adding an HTTP query parameter + + ``o=`` followed by the field name. A sequence of fields can be used + + to create a complete ordering by adding a sequence of ``o`` HTTP query + + parameters. To reverse the natural order of a field, prefix the field + + name by a minus (-) sign. + + + **Tags: profile + + + **Examples + + + .. code-block:: http + + GET /api/accounts/?o=created_at HTTP/1.1 + + responds + + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [{ + "slug": "xia", + "full_name": "Xia Lee", + "printable_name": "Xia Lee", + "created_at": "2016-01-14T23:16:55Z" + }] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in slug, full_name, email, phone, + street_address, locality, region, postal_code, country, username, + first_name, last_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by u, r + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Organization" + tags: + - accounts + parameters: [] + /accounts/profiles/: + get: + operationId: accounts_profiles_list + description: >- + Queries a page (``PAGE_SIZE`` records) of candidate profiles based + + of a search criteria (``q``). + + + This API differs from /api/profile in that it is designed to be used + + in auto-completion input fields instead of designed to list all profiles. + + + The queryset can be ordered by a field by adding an HTTP query parameter + + ``o=`` followed by the field name. A sequence of fields can be used + + to create a complete ordering by adding a sequence of ``o`` HTTP query + + parameters. To reverse the natural order of a field, prefix the field + + name by a minus (-) sign. + + + **Tags: profile + + + **Examples + + + .. code-block:: http + + GET /api/accounts/profile/?q=xia HTTP/1.1 + + responds + + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [{ + "slug": "xia", + "full_name": "Xia Lee", + "printable_name": "Xia Lee", + "created_at": "2016-01-14T23:16:55Z" + }] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in slug, full_name, email, phone, + street_address, locality, region, postal_code, country, username, + first_name, last_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by u, r + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Organization" + tags: + - accounts + parameters: [] + /accounts/users/: + get: + operationId: accounts_users_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``User``. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + **Tags: profile + + + **Examples + + + .. code-block:: http + + GET /api/users/?o=created_at&ot=desc HTTP/1.1 + + responds + + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "slug": "alice", + "email": "alice@djaodjin.com", + "full_name": "Alice Cooper", + "created_at": "2014-01-01T00:00:00Z" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: o + in: query + description: sort by first_name, last_name, email, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in first_name, last_name, email + required: false + schema: + type: string + example: query + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/User" + tags: + - accounts + parameters: [] + /auth/: + post: + operationId: auth_create + description: >- + Returns a JSON Web Token that can be used in requests that require + + authentication. + + + **Tags: auth + + + **Example + + + .. code-block:: http + + POST /api/auth/ HTTP/1.1 + + .. code-block:: json + + { + "username": "donny", + "password": "yoyo" + } + + responds + + + .. code-block:: json + + {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A"} + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Credentials" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Token" + "400": + description: parameters error + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationError" + tags: + - auth + parameters: [] + /auth/logout/: + post: + operationId: auth_logout_create + description: |- + Removes all cookies associated with the session. + + This API endpoint is only useful when the user is using Cookie-based + authentication. Tokens expire; they cannot be revoked. + + **Tags: auth + + **Example + + .. code-block:: http + + POST /api/auth/logout/ HTTP/1.1 + + .. code-block:: json + + { + "token": "670yoaq34rotlgqpoxzmw435Alrdf" + } + requestBody: + $ref: "#/components/requestBodies/Token" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Token" + tags: + - auth + parameters: [] + /auth/recover/: + post: + operationId: auth_recover_create + description: "" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordReset" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordReset" + tags: + - auth + parameters: [] + /auth/register/: + post: + operationId: auth_register_create + description: >- + Creates a new user and returns a JSON Web Token that can subsequently + + be used to authenticate the new user in HTTP requests. + + + **Tags: auth + + + **Example + + + .. code-block:: http + + POST /api/auth/register/ HTTP/1.1 + + .. code-block:: json + + { + "username": "joe1", + "password": "yoyo", + "email": "joe+1@example.com", + "full_name": "Joe Card1" + } + + responds + + + .. code-block:: json + + { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImpvZTEiLCJlbWFpbCI6ImpvZSsxQGRqYW9kamluLmNvbSIsImZ1bGxfbmFtZSI6IkpvZSAgQ2FyZDEiLCJleHAiOjE1Mjk2NTUyMjR9.GFxjU5AvcCQbVylF1PJwcBUUMECj8AKxsHtRHUSypco" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateUser" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Token" + "400": + description: parameters error + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationError" + tags: + - auth + parameters: [] + /auth/tokens/: + post: + operationId: auth_tokens_create + description: >- + Refreshes a JSON Web Token by verifying the token and creating + + a new one that expires further in the future. + + + The authenticated user and the user associated to the token should be + + identical. + + + **Tags: auth + + + **Example + + + .. code-block:: http + + POST /api/tokens/ HTTP/1.1 + + .. code-block:: json + + { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" + } + + .. code-block:: json + + { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5Njk1NjA1fQ.-uuZb8R68jWw1Tc9FJocOWe1KHFklRffXbH0Rg6d_0c" + } + requestBody: + $ref: "#/components/requestBodies/Token" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Token" + tags: + - auth + parameters: [] + /auth/tokens/realms/: + get: + operationId: auth_tokens_realms_read + description: |- + Gets temporary credentials to access S3 directly from the browser. + + **Examples + + .. code-block:: http + + GET /api/auth/realms/cowork/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "location": "", + "access_key": "", + "acl": "private", + "policy": "", + "signature": "", + "security_token": "", + "x_amz_credential": "", + "x_amz_date": "" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/AuthRealms" + tags: + - auth + parameters: [] + "/auth/tokens/realms/{organization}/": + get: + operationId: auth_tokens_realms_org_read + description: |- + Gets temporary credentials to access S3 directly from the browser. + + **Examples + + .. code-block:: http + + GET /api/auth/realms/cowork/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "location": "", + "access_key": "", + "acl": "private", + "policy": "", + "signature": "", + "security_token": "", + "x_amz_credential": "", + "x_amz_date": "" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/AuthRealms" + tags: + - auth + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + /auth/tokens/verify/: + post: + operationId: auth_tokens_verify_create + description: >- + Verifies a JSON Web Token. + + + The authenticated user and the user associated to the token should be + + identical. + + + **Tags: auth + + + **Example + + + .. code-block:: http + + POST /api/tokens/verify/ HTTP/1.1 + + .. code-block:: json + + { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" + } + + responds + + + .. code-block:: json + + { + "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6ImRvbm55IiwiZW1haWwiOiJzbWlyb2xvKzRAZGphb2RqaW4uY29tIiwiZnVsbF9uYW1lIjoiRG9ubnkgQ29vcGVyIiwiZXhwIjoxNTI5NjU4NzEwfQ.F2y1iwj5NHlImmPfSff6IHLN7sUXpBFmX0qjCbFTe6A" + } + requestBody: + $ref: "#/components/requestBodies/Token" + responses: + "200": + description: Token is valid + content: + application/json: + schema: + $ref: "#/components/schemas/Token" + "400": + description: Token is invalid + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationError" + tags: + - auth + parameters: [] + /billing/charges/: + get: + operationId: billing_charges_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Charge`` that were created + + on the processor. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/charges?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1 + + Retrieve the list of charges that were created before + + 2015-07-05T07:00:00.000Z, sort them by date in descending order. + + + .. code-block:: json + + { + "count": 1, + "unit": "usd", + "total": "112120", + "next": null, + "previous": null, + "results": [{ + "created_at": "2016-01-01T00:00:00Z", + "readable_amount": "$1121.20", + "amount": 112120, + "unit": "usd", + "description": "Charge for subscription to cowork open-space", + "last4": "1234", + "exp_date"" "12/2016", + "processor_key": "ch_XAb124EF", + "state": "DONE" + } ...] + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: o + in: query + description: sort by description, amount, Full name, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in description, processor_key, + customer__full_name + required: false + schema: + type: string + example: query + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - total + - count + - results + type: object + properties: + total: + description: The sum of all Charge amount (in unit) + type: integer + count: + description: The number of records + type: integer + next: + description: API end point to get the next pageof records matching the + query + type: string + format: uri + previous: + description: API end point to get the previous pageof records matching + the query + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Charge" + tags: + - billing + parameters: [] + "/billing/charges/{charge}/": + get: + operationId: billing_charges_read + description: |- + Pass through to the processor and returns details about a ``Charge``. + + **Tags: billing + + **Examples + + .. code-block:: http + + GET /api/billing/charges/ch_XAb124EF/ HTTP/1.1 + + .. code-block:: json + + { + "created_at": "2016-01-01T00:00:00Z", + "readable_amount": "$1121.20", + "amount": 112120, + "unit": "usd", + "description": "Charge for subscription to cowork open-space", + "last4": "1234", + "exp_date"" "12/2016", + "processor_key": "ch_XAb124EF", + "state": "DONE" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Charge" + tags: + - billing + parameters: + - name: charge + in: path + required: true + schema: + type: string + example: ch_XAb124EF + "/billing/charges/{charge}/email/": + post: + operationId: billing_charges_email_create + description: |- + Email the charge receipt to the customer email address on file. + + **Tags: billing + + **Example + + .. code-block:: http + + POST /api/billing/charges/ch_XAb124EF/email/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "charge_id": "ch_XAb124EF", + "email": "joe@localhost.localdomain" + } + + The service sends a duplicate e-mail receipt for charge `ch_XAb124EF` + to the e-mail address of the customer, i.e. `joe@localhost.localdomain`. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/EmailChargeReceipt" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/EmailChargeReceipt" + tags: + - billing + parameters: + - name: charge + in: path + required: true + schema: + type: string + example: ch_XAb124EF + "/billing/charges/{charge}/refund/": + post: + operationId: billing_charges_refund_create + description: >- + Partially or totally refund all or a subset of line items on a + ``Charge``. + + + **Tags: billing + + + **Example + + + .. code-block:: http + + POST /api/billing/charges/ch_XAb124EF/refund/ HTTP/1.1 + + .. code-block:: json + + { + "lines": [ + { + "num": 0, + "refunded_amount": 4000, + }, + { + "num": 1, + "refunded_amount": 82120, + } + ] + } + + Refunds $40 and $821.20 from first and second line item on the receipt + + respectively. The API call responds with the Charge. + + + .. code-block:: json + + { + "created_at": "2016-01-01T00:00:00Z", + "readable_amount": "$1121.20", + "amount": 112120, + "unit": "usd", + "description": "Charge for subscription to cowork open-space", + "last4": "1234", + "exp_date"" "12/2016", + "processor_key": "ch_XAb124EF", + "state": "DONE" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RefundCharge" + required: true + responses: + "200": + description: Refund successful + content: + application/json: + schema: + $ref: "#/components/schemas/Charge" + "400": + description: parameters error + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationError" + tags: + - billing + parameters: + - name: charge + in: path + required: true + schema: + type: string + example: ch_XAb124EF + /billing/transactions/: + get: + operationId: billing_transactions_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Transaction`` from + + the :doc:`ledger `. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/transactions?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1 + + responds + + + .. code-block:: json + + { + "ends_at": "2017-03-30T18:10:12.962859Z", + "balance": 11000, + "unit": "usd", + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2017-02-01T00:00:00Z", + "description": "Charge for 4 periods", + "amount": "($356.00)", + "is_debit": true, + "orig_account": "Liability", + "orig_organization": "xia", + "orig_amount": 112120, + "orig_unit": "usd", + "dest_account": "Funds", + "dest_organization": "stripe", + "dest_amount": 112120, + "dest_unit": "usd" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in descr, orig_organization__full_name, + dest_organization__full_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by description, amount, dest_organization, dest_account, + orig_organization, orig_account, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - balance + - unit + - count + - results + type: object + properties: + balance: + description: balance of all transactions in cents (i.e. 100ths) of unit + type: integer + unit: + description: "three-letter ISO 4217 code for currency unit (ex: usd)" + type: integer + count: + description: The number of records + type: integer + next: + description: API end point to get the next pageof records matching the + query + type: string + format: uri + previous: + description: API end point to get the previous pageof records matching + the query + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Transaction" + tags: + - billing + parameters: [] + "/billing/{organization}/balance/cancel/": + delete: + operationId: billing_balance_cancel_delete + description: |- + Cancel the balance for a provider organization. This will create + a transaction for this balance cancellation. A manager can use + this endpoint to cancel balance dues that is known impossible + to be recovered (e.g. an external bank or credit card company + act). + + The endpoint returns the transaction created to cancel the + balance due. + + **Tags: billing + + **Examples + + .. code-block:: http + + DELETE /api/billing/cowork/balance/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/bank/": + get: + operationId: billing_bank_read + description: >- + Pass through that calls the processor API to retrieve some details about + + the deposit account associated to a provider (if that information is + + available through the :doc:`payment processor backend` API). + + + This API does not trigger payment of a subscriber to a provider. Checkout + + of a subscription cart is done either through the + + :ref:`HTML page` or :ref:`API end point`. + + + **Examples + + + .. code-block:: http + + GET /api/billing/cowork/bank/ HTTP/1.1 + + responds + + + .. code-block:: json + + { + "bank_name": "Stripe Test Bank", + "last4": "***-htrTZ", + "balance_amount": 0, + "balance_unit": "usd" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Bank" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/card/": + get: + operationId: billing_card_read + description: |- + Pass through to the processor to retrieve some details about + the payment method (ex: credit card) associated to a subscriber. + + **Examples + + .. code-block:: http + + GET /api/billing/cowork/card/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "last4": "1234", + "exp_date": "12/2019" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Card" + tags: + - billing + put: + operationId: billing_card_update + description: |- + Pass through to the processor to update some details about + the payment method (ex: credit card) associated to a subscriber. + + **Examples + + .. code-block:: http + + PUT /api/billing/cowork/card/ HTTP/1.1 + + .. code-block:: json + + { + "token": "xyz", + } + + responds + + .. code-block:: json + + { + "last4": "1234", + "exp_date": "12/2019" + } + requestBody: + $ref: "#/components/requestBodies/Card" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Card" + tags: + - billing + patch: + operationId: billing_card_partial_update + description: |- + Pass through to the processor to retrieve some details about + the payment method (ex: credit card) associated to a subscriber. + + **Examples + + .. code-block:: http + + GET /api/billing/cowork/card/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "last4": "1234", + "exp_date": "12/2019" + } + requestBody: + $ref: "#/components/requestBodies/Card" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Card" + tags: + - billing + delete: + operationId: billing_card_delete + description: |- + Pass through to the processor to remove the payment method (ex: credit + card) associated to a subscriber. + + **Examples + + .. code-block:: http + + DELETE /api/billing/cowork/card/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/checkout/": + get: + operationId: billing_checkout_read + description: >- + Get a list indexed by plans of items that will be charged + + (`lines`) and options that could be charged instead. + + + In many subscription businesses, it is possible to buy multiple + + period in advance at a discount. The options reflects that. + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/xia/checkout HTTP/1.1 + + responds + + + .. code-block:: json + + {"items": + [{ + "subscription":{ + "created_at":"2016-06-21T23:24:09.242925Z", + "ends_at":"2016-10-21T23:24:09.229768Z", + "description":null, + "organization":{ + "slug":"xia", + "full_name":"Xia", + "printable_name":"Xia", + "created_at":"2012-08-14T23:16:55Z", + "email":"xia@localhost.localdomain" + }, + "plan":{ + "slug":"basic", + "title":"Basic", + "description":"Basic Plan", + "is_active":true, + "setup_amount":0, + "period_amount":2000, + "interval":4, + "app_url":"/app/" + }, + "auto_renew":true + }, + "lines":[{ + "created_at":"2016-06-21T23:42:13.863739Z", + "description":"Subscription to basic until 2016/11/21 (1 month)", + "amount":"$20.00", + "is_debit":false, + "orig_account":"Receivable", + "orig_organization":"cowork", + "orig_amount":2000, + "orig_unit":"usd", + "dest_account":"Payable", + "dest_organization":"xia", + "dest_amount":2000, + "dest_unit":"usd" + }], + "options":[] + }] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationCart" + tags: + - billing + post: + operationId: billing_checkout_create + description: >- + Places an order for the subscription items in the cart and creates + + a ``Charge`` on the ``{organization}`` payment card. + + + If the charge fails a balance is due, to be collected later. + + + The cart is manipulated through various API endpoints: + + + - `/api/cart/redeem/` applies a coupon code for a potential discount. + + - `/api/cart/` adds or updates a cart item. + + - `/api/cart/{plan}` removes a cart item. + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + POST /api/billing/xia/checkout + + { + "remember_card": true, + "processor_token": "tok_23prgoqpstf56todq" + } + + responds + + + .. code-block:: json + + { + "created_at": "2016-06-21T23:42:44.270977Z", + "processor_key": "pay_5lK5TacFH3gbKe" + "amount": 2000, + "unit": "usd", + "description": "Charge pay_5lK5TacFH3gblP on credit card"" of Xia", + "last4": "1234", + "exp_date": "2016-06-01", + "state": "created" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Checkout" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Charge" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: xia + "/billing/{organization}/coupons/": + get: + operationId: billing_coupons_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Coupon`` associated + + to a provider. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/cowork/coupons?o=code&ot=asc&q=DIS HTTP/1.1 + + retrieves the list of Coupon for provider cowork where `code` + + matches 'DIS', ordered by `code` in ascending order. + + + .. code-block:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "code": "DIS100", + "percent": 100, + "created_at": "2014-01-01T09:00:00Z", + "ends_at": null, + "description": null + }, + { + "code": "DIS50", + "percent": 50, + "created_at": "2014-01-01T09:00:00Z", + "ends_at": null, + "description": null + } + ] + } + parameters: + - name: o + in: query + description: sort by code, created_at, description, ends_at, percent + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in code, description, percent, + organization__full_name + required: false + schema: + type: string + example: query + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Coupon" + tags: + - billing + post: + operationId: billing_coupons_create + description: |- + Creates a ``Coupon`` to be used on provider's plans. + + Customers will be able to use the `code` until `ends_at` + to subscribe to plans from the Coupon's provider at a discount. + + **Examples + + .. code-block:: http + + POST /api/billing/cowork/coupons HTTP/1.1 + + .. code-block:: json + + { + "code": "DIS100", + "percent": 100, + "ends_at": null, + "description": null + } + requestBody: + $ref: "#/components/requestBodies/Coupon" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Coupon" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/coupons/{coupon}/": + get: + operationId: billing_coupons_read + description: |- + Retrieves a ``Coupon``. + + **Tags: billing + + **Examples + + .. code-block:: http + + GET /api/billing/cowork/coupons/DIS100 HTTP/1.1 + + .. code-block:: json + + { + "code": "DIS100", + "percent": 100, + "created_at": "2014-01-01T09:00:00Z", + "ends_at": null, + "description": null + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Coupon" + tags: + - billing + put: + operationId: billing_coupons_update + description: |- + Updates a ``Coupon``. + + **Tags: billing + + **Examples + + .. code-block:: http + + PUT /api/billing/cowork/coupons/DIS100 HTTP/1.1 + + .. code-block:: json + + { + "percent": 100, + "ends_at": null, + "description": null + } + requestBody: + $ref: "#/components/requestBodies/Coupon" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Coupon" + tags: + - billing + patch: + operationId: billing_coupons_partial_update + description: |- + Retrieves a ``Coupon``. + + **Tags: billing + + **Examples + + .. code-block:: http + + GET /api/billing/cowork/coupons/DIS100 HTTP/1.1 + + .. code-block:: json + + { + "code": "DIS100", + "percent": 100, + "created_at": "2014-01-01T09:00:00Z", + "ends_at": null, + "description": null + } + requestBody: + $ref: "#/components/requestBodies/Coupon" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Coupon" + tags: + - billing + delete: + operationId: billing_coupons_delete + description: |- + Deletes a ``Coupon``. + + Only coupons which have never been applied to an oder will + be permanently deleted. Coupons which have already be used + at least once will be de-activated and still available for + performance measurements. + + **Tags: billing + + **Examples + + .. code-block:: http + + DELETE /api/billing/cowork/coupons/DIS100 HTTP/1.1 + responses: + "204": + description: "" + tags: + - billing + parameters: + - name: coupon + in: path + required: true + schema: + type: string + example: DIS100 + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/history/": + get: + operationId: billing_history_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Transaction`` associated + + to ``{organization}`` while the organization acts as a subscriber. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + This API end point is typically used to display orders, payments and refunds + + of a subscriber (see :ref:`subscribers pages <_pages_subscribers>`) + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/xia/history?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "balance": 11000, + "unit": "usd", + "results": [ + { + "created_at": "2015-08-01T00:00:00Z", + "description": "Charge for 4 periods", + "amount": "($356.00)", + "is_debit": true, + "orig_account": "Liability", + "orig_organization": "xia", + "orig_amount": 112120, + "orig_unit": "usd", + "dest_account": "Funds", + "dest_organization": "stripe", + "dest_amount": 112120, + "dest_unit": "usd" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in descr, orig_organization__full_name, + dest_organization__full_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by description, amount, dest_organization, dest_account, + orig_organization, orig_account, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Transaction" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: xia + "/billing/{organization}/receivables/": + get: + operationId: billing_receivables_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Transaction`` marked + + as receivables associated to ``{organization}`` while the organization + + acts as a provider. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + This API endpoint is typically used to find all sales for ``{organization}`` + + whether it was paid or not. + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/cowork/receivables?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "total": "112120", + "unit": "usd", + "next": null, + "previous": null, + "results": [ + { + "created_at": "2015-08-01T00:00:00Z", + "description": "Charge 1123 distribution for demo562-open-plus", + "amount": "112120", + "is_debit": false, + "orig_account": "Funds", + "orig_organization": "stripe", + "orig_amount": 112120, + "orig_unit": "usd", + "dest_account": "Funds", + "dest_organization": "cowork", + "dest_amount": 112120, + "dest_unit": "usd" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in descr, orig_organization__full_name, + dest_organization__full_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by description, amount, dest_organization, dest_account, + orig_organization, orig_account, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Transaction" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/transfers/": + get: + operationId: billing_transfers_list + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Transaction`` associated + + to ``{organization}`` while the organization acts as a provider. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + This API endpoint is typically used to find sales, payments, refunds + + and bank deposits for a provider. + + (see :ref:`provider pages <_pages_provider_transactions>`) + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + GET /api/billing/cowork/transfers?start_at=2015-07-05T07:00:00.000Z&o=date&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2015-08-01T00:00:00Z", + "description": "Charge 1123 distribution for demo562-open-plus", + "amount": "$1121.20", + "is_debit": false, + "orig_account": "Funds", + "orig_organization": "stripe", + "orig_amount": 112120, + "orig_unit": "usd", + "dest_account": "Funds", + "dest_organization": "cowork", + "dest_amount": 112120, + "dest_unit": "usd" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in descr, orig_organization__full_name, + dest_organization__full_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by description, amount, dest_organization, dest_account, + orig_organization, orig_account, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Transaction" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/billing/{organization}/transfers/import/": + post: + operationId: billing_transfers_import_create + description: |- + Inserts transactions that were done offline. + + The primary purpose of this API call is for a provider to keep + accurate metrics for the performance of the product sold, regardless + of payment options (online or offline). + + **Tags: billing + + **Examples + + .. code-block:: http + + POST /api/billing/cowork/transfers/import/ HTTP/1.1 + + .. code-block:: json + + { + "subscription": "demo562-open-plus", + "amount": "10.00", + "descr": "Paid by check" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/OfflineTransaction" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/OfflineTransaction" + tags: + - billing + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + /cart/: + post: + operationId: cart_create + description: >- + Adds a ``Plan`` into the cart of the ``request.user``. + + + The cart can later be checked out and paid by an ``Organization``, + + either through the :ref:`HTML page` + + or :ref:`API end point`. + + + This end point is typically used when a user is presented with a list + + of add-ons that she can subscribes to in one checkout screen. The end-point + + works in both cases, authenticated or anonymous users. For authenticated + + users, the cart is stored in the database as ``CartItem`` objects. + + For anonymous users, the cart is stored in an HTTP Cookie. + + + The end-point accepts a single item or a list of items. + + + ``quantity`` is optional. When it is not specified, subsquent checkout + + screens will provide choices to pay multiple periods in advance + + When additional ``full_name``, ``email`` and ``sync_on`` are specified, + + payment can be made by one ``Organization`` for another ``Organization`` + + to be subscribed (see :ref:`GroupBuy orders`). + + + **Tags: billing + + + **Examples + + + .. code-block:: http + + POST /api/cart/ HTTP/1.1 + + .. code-block:: json + + { + "plan": "open-space", + "option": 1 + } + + responds + + + .. code-block:: json + + { + "plan": "open-space", + "option": 1 + } + + ``option`` is optional. When it is not specified, subsquent checkout + + screens will provide choices to pay multiple periods in advance + + When additional ``full_name`` and ``sync_on`` are specified, + + payment can be made by one ``Organization`` for another ``Organization`` + + to be subscribed (see :ref:`GroupBuy orders`). + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CartItemCreate" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/CartItemCreate" + tags: + - cart + delete: + operationId: cart_delete + description: |- + Removes an item from the ``request.user`` cart. + + **Tags: billing + + **Examples + + .. code-block:: http + + DELETE /api/cart/?plan=open-space HTTP/1.1 + responses: + "204": + description: "" + tags: + - cart + parameters: [] + /cart/redeem/: + post: + operationId: cart_redeem_create + description: |- + Redeems a ``Coupon`` and applies the discount to the eligible items + in the cart. + + **Tags: billing + + **Examples + + .. code-block:: http + + POST /api/redeem HTTP/1.1 + + .. code-block:: json + + { + "code": "LABORDAY" + } + + responds + + .. code-block:: json + + { + "details": "Coupon 'LABORDAY' was successfully applied." + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RedeemCoupon" + required: true + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationError" + tags: + - cart + parameters: [] + "/cart/{plan}/upload/": + post: + operationId: cart_upload_create + description: |- + Add a ``Plan`` into the subscription cart of multiple users as per the + content of an uploaded file. + + This works bulk fashion of :ref:`/cart/ endpoint`. The + uploaded file must be a CSV containing the fields ``first_name``, + ``last_name`` and email. The CSV file must not contain a header + line, only data. + + **Tags: billing + + **Examples + + Content of ``names.csv``: + + .. code-block:: csv + + Joe,Smith,joesmith@example.com + Marie,Johnson,mariejohnson@example.com + + .. code-block:: http + + POST /api/cart/basic/upload/ HTTP/1.1 + + Content-Disposition: form-data; name="file"; filename="names.csv" + Content-Type: text/csv + + responds + + .. code-block:: json + + { + "created" [ + { + "first_name": "Joe", + "last_name": "Smith", + "email": "joesmith@example.com" + }, + { + "first_name": "Marie", + "last_name": "Johnson", + "email": "mariejohnson@example.com" + } + ], + "updated": [], + "failed": [] + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CartItemUpload" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/CartItemUpload" + tags: + - cart + parameters: + - name: plan + in: path + required: true + schema: + type: string + example: basic + "/contacts/{user}/activities/": + get: + operationId: contacts_activities_list + description: |- + Lists activities for a contact. + + **Tags: profile + + **Example + + .. code-block:: http + + GET /api/contacts/xia/activities HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [{ + "created_at": "2018-01-01T00:00:00Z", + "created_by": "alice", + "text": "Phone call", + "account": null + },{ + "created_at": "2018-01-02T00:00:00Z", + "created_by": "alice", + "text": "Follow up e-mail", + "account": "cowork" + }] + } + parameters: + - name: q + in: query + description: A search term. + required: false + schema: + type: string + example: query + - name: o + in: query + description: Which field to use when ordering the results. + required: false + schema: + type: string + example: created_at + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Activity" + tags: + - contacts + post: + operationId: contacts_activities_create + description: |- + Records new activity with a contact. + + **Tags: profile + + **Examples + + .. code-block:: http + + POST /api/contacts/xia/activities/ HTTP/1.1 + + .. code-block:: json + + { + "text": "Phone call", + "account": null + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Activity" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Activity" + tags: + - contacts + parameters: + - name: user + in: path + required: true + schema: + type: string + example: xia + "/legal/{agreement}/sign/": + post: + operationId: legal_sign_create + description: "" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/AgreementSign" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/AgreementSign" + tags: + - legal + parameters: + - name: agreement + in: path + required: true + schema: + type: string + example: slug + "/metrics/balances/{report}/": + get: + operationId: metrics_balances_read + description: |- + Queries a balance sheet named ``{report}`` for the broker. + + To add lines in the report see `/api/metrics/balances/{report}/lines/`. + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/balances/taxes/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "scale": 0.01, + "unit": "usd", + "title": "Balances: taxes", + "table": [ + { + "key": "Sales", + "selector": "Receivable", + "values": [ + ["2015-05-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 0], + ["2015-11-01T00:00:00Z", 0], + ["2016-02-01T00:00:00Z", 0], + ["2016-05-01T00:00:00Z", 0], + ["2016-05-16T21:08:15.637Z", 0] + ] + } + ] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Metrics" + tags: + - metrics + parameters: + - name: report + in: path + required: true + schema: + type: string + example: taxes + "/metrics/balances/{report}/lines/": + get: + operationId: metrics_balances_lines_list + description: |- + Queries the list of rows reported on a balance sheet named `{report}`. + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/balances/taxes/lines/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + ] + } + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/BalanceLine" + tags: + - metrics + post: + operationId: metrics_balances_lines_create + description: |- + Adds a new row on the ``{report}`` balance sheet. + + **Tags: metrics + + **Examples + + .. code-block:: http + + POST /api/metrics/balances/taxes/lines/ HTTP/1.1 + + .. code-block:: json + + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + + responds + + .. code-block:: json + + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + requestBody: + $ref: "#/components/requestBodies/BalanceLine" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/BalanceLine" + tags: + - metrics + patch: + operationId: metrics_balances_lines_partial_update + description: |- + Updates the order in which lines are displayed. + + When receiving a request like [{u'newpos': 1, u'oldpos': 3}], + it will move the line at position 3 to position 1, updating the + rank of all lines in-between. + + **Tags: metrics + requestBody: + $ref: "#/components/requestBodies/BalanceLine" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/BalanceLine" + tags: + - metrics + parameters: + - name: report + in: path + required: true + schema: + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + example: taxes + "/metrics/balances/{report}/lines/{rank}/": + get: + operationId: metrics_balances_lines_read + description: |- + Describes a row reported on a balance sheet named `{report}`. + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/balances/taxes/lines/1/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/BalanceLine" + tags: + - metrics + put: + operationId: metrics_balances_lines_update + description: |- + Updates a row reported on a balance sheet named `{report}`. + + **Tags: metrics + + **Examples + + .. code-block:: http + + PUT /api/metrics/balances/taxes/lines/1/ HTTP/1.1 + + .. code-block:: json + + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + + responds + + .. code-block:: json + + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + requestBody: + $ref: "#/components/requestBodies/BalanceLine" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/BalanceLine" + tags: + - metrics + patch: + operationId: metrics_balances_lines_partial_update_2 + description: |- + Describes a row reported on a balance sheet named `{report}`. + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/balances/taxes/lines/1/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "title": "Sales", + "selector": "Receivable", + "rank": 1 + } + requestBody: + $ref: "#/components/requestBodies/BalanceLine" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/BalanceLine" + tags: + - metrics + delete: + operationId: metrics_balances_lines_delete + description: |- + Deletes a row reported on a balance sheet named `{report}`. + + **Tags: metrics + + **Examples + + .. code-block:: http + + DELETE /api/metrics/balances/taxes/lines/1/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - metrics + parameters: + - name: rank + in: path + required: true + schema: + type: string + example: 1 + - name: report + in: path + required: true + schema: + type: string + example: taxes + /metrics/registered/: + get: + operationId: metrics_registered_list + description: >- + Lists all ``User`` which have no associated role or a role + + to an ``Organization`` which has no Subscription, active or inactive. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + **Tags: metrics + + + **Examples + + + .. code-block:: http + + GET /api/metrics/registered?o=created_at&ot=desc HTTP/1.1 + + responds + + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "slug": "alice", + "email": "alice@djaodjin.com", + "full_name": "Alice Cooper", + "created_at": "2014-01-01T00:00:00Z" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: o + in: query + description: sort by first_name, last_name, email, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in first_name, last_name, email + required: false + schema: + type: string + example: query + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/User" + tags: + - metrics + parameters: [] + "/metrics/{organization}/active/": + get: + operationId: metrics_active_list + description: >- + Lists all ``Subscription`` to a plan whose provider is + + ``{organization}`` and which are currently in progress. + + + Optionnaly when an ``ends_at`` query parameter is specified, + + returns a queryset of ``Subscription`` that were active + + at ``ends_at``. When a ``start_at`` query parameter is specified, + + only considers ``Subscription`` that were created after ``start_at``. + + + The queryset can be filtered for at least one field to match a search + + term (``q``). + + + Query results can be ordered by natural fields (``o``) in either ascending + + or descending order (``ot``). + + + **Tags: metrics + + + **Examples + + + .. code-block:: http + + GET /api/metrics/cowork/active?o=created_at&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2016-01-14T23:16:55Z", + "ends_at": "2017-01-14T23:16:55Z", + "description": null, + "organization": { + "slug": "xia", + "printable_name": "Xia Lee" + }, + "plan": { + "slug": "open-space", + "title": "Open Space", + "description": "open space desk, High speed internet + - Ethernet or WiFi, Unlimited printing, + Unlimited scanning, Unlimited fax service + (send and receive)", + "is_active": true, + "setup_amount": 0, + "period_amount": 17999, + "interval": 4, + "app_url": "http://localhost:8020/app" + }, + "auto_renew": true + } + ] + } + parameters: + - name: o + in: query + description: sort by organization, plan, created_at, ends_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in organization__slug, + organization__full_name, organization__email, organization__phone, + organization__street_address, organization__locality, + organization__region, organization__postal_code, + organization__country, plan__title + required: false + schema: + type: string + example: query + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Subscription" + tags: + - metrics + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/metrics/{organization}/balances/": + get: + operationId: metrics_balances_list + description: |- + Generate a table of revenue (rows) per months (columns). + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/cowork/balances HTTP/1.1 + + .. code-block:: json + + { + "title": "Balances", + "scale": 0.01, + "unit": "usd", + "table": [ + { + "key": "Income", + "values": [ + ["2014-09-01T00:00:00Z", 0], + ["2014-10-01T00:00:00Z", 1532624], + ["2014-11-01T00:00:00Z", 2348340], + ["2014-12-01T00:00:00Z", 3244770], + ["2015-01-01T00:00:00Z", 5494221], + ["2015-02-01T00:00:00Z", 7214221], + ["2015-03-01T00:00:00Z", 8444221], + ["2015-04-01T00:00:00Z", 9784221], + ["2015-05-01T00:00:00Z", 12784221], + ["2015-06-01T00:00:00Z", 14562341], + ["2015-07-01T00:00:00Z", 16567341], + ["2015-08-01T00:00:00Z", 17893214], + ["2015-08-06T02:24:50.485Z", 221340] + ], + }, + { + "key": "Backlog", + "values": [ + ["2014-09-01T00:00:00Z", 1712624], + ["2014-10-01T00:00:00Z", 3698340], + ["2014-11-01T00:00:00Z", 7214770], + ["2014-12-01T00:00:00Z", 10494221], + ["2015-01-01T00:00:00Z", 14281970], + ["2015-02-01T00:00:00Z", 18762845], + ["2015-03-01T00:00:00Z", 24258765], + ["2015-04-01T00:00:00Z", 31937741], + ["2015-05-01T00:00:00Z", 43002401], + ["2015-06-01T00:00:00Z", 53331444], + ["2015-07-01T00:00:00Z", 64775621], + ["2015-08-01T00:00:00Z", 75050033], + ["2015-08-06T02:24:50.485Z", 89156321] + ], + }, + { + "key": "Receivable", + "values": [ + ["2014-09-01T00:00:00Z", 0], + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 0], + ["2015-02-01T00:00:00Z", 0], + ["2015-03-01T00:00:00Z", 0], + ["2015-04-01T00:00:00Z", 0], + ["2015-05-01T00:00:00Z", 0], + ["2015-06-01T00:00:00Z", 0], + ["2015-07-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 0], + ["2015-08-06T02:24:50.485Z", 0] + ], + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Metrics" + tags: + - metrics + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/metrics/{organization}/churned/": + get: + operationId: metrics_churned_list + description: >- + Lists all ``Subscription`` to a plan whose provider is + + ``:organization`` which have ended already. + + + The queryset can be further filtered to a range of dates between + + ``start_at`` and ``ends_at``. + + + The queryset can be further filtered by passing a ``q`` parameter. + + The result queryset can be ordered. + + + **Tags: metrics + + + **Examples + + + .. code-block:: http + + GET /api/metrics/cowork/churned?o=created_at&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2016-01-14T23:16:55Z", + "ends_at": "2017-01-14T23:16:55Z", + "description": null, + "organization": { + "slug": "xia", + "printable_name": "Xia Lee" + }, + "plan": { + "slug": "open-space", + "title": "Open Space", + "description": "open space desk, High speed internet + - Ethernet or WiFi, Unlimited printing, + Unlimited scanning, Unlimited fax service + (send and receive)", + "is_active": true, + "setup_amount": 0, + "period_amount": 17999, + "interval": 4, + "app_url": "http://localhost:8020/app" + }, + "auto_renew": true + } + ] + } + parameters: + - name: o + in: query + description: sort by organization, plan, created_at, ends_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in organization__slug, + organization__full_name, organization__email, organization__phone, + organization__street_address, organization__locality, + organization__region, organization__postal_code, + organization__country, plan__title + required: false + schema: + type: string + example: query + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Subscription" + tags: + - metrics + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/metrics/{organization}/coupons/{coupon}/": + get: + operationId: metrics_coupons_read + description: >- + Queries a page (``PAGE_SIZE`` records) of ``Coupon`` usage. + + + The queryset can be filtered to a range of dates + + ([``start_at``, ``ends_at``]) and for at least one field to match a search + + term (``q``). + + + The result queryset can be ordered by passing an ``o`` (field name) + + and ``ot`` (asc or desc) parameter. + + + **Tags: metrics + + + **Examples + + + .. code-block:: http + + GET /api/metrics/cowork/coupons/DIS100/ HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "user": { + "slug": "xia", + "email": "xia@localhost.localdomain", + "full_name": "Xia Doe", + "created_at": "2012-09-14T23:16:55Z" + }, + "plan": "basic", + "created_at": "2014-01-01T09:00:00Z" + } + ] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/CartItem" + tags: + - metrics + parameters: + - name: coupon + in: path + required: true + schema: + type: string + example: DIS100 + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/metrics/{organization}/customers/": + get: + operationId: metrics_customers_list + description: |- + Produce revenue stats + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/cowork/customers HTTP/1.1 + + .. code-block:: json + + { + "title": "Customers" + "table": [ + { + "key": "Total # of Customers", + "values": [ + ["2014-10-01T00:00:00Z", 15], + ["2014-11-01T00:00:00Z", 17], + ["2014-12-01T00:00:00Z", 19], + ["2015-01-01T00:00:00Z", 19], + ["2015-02-01T00:00:00Z", 25], + ["2015-03-01T00:00:00Z", 29], + ["2015-04-01T00:00:00Z", 37], + ["2015-05-01T00:00:00Z", 43], + ["2015-06-01T00:00:00Z", 46], + ["2015-07-01T00:00:00Z", 48], + ["2015-08-01T00:00:00Z", 54], + ["2015-08-06T05:20:24.537Z", 60] + ] + }, + { + "key": "# of new Customers" + "values": [ + ["2014-10-01T00:00:00Z", 2], + ["2014-11-01T00:00:00Z", 2], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 6], + ["2015-02-01T00:00:00Z", 4], + ["2015-03-01T00:00:00Z", 8], + ["2015-04-01T00:00:00Z", 6], + ["2015-05-01T00:00:00Z", 3], + ["2015-06-01T00:00:00Z", 2], + ["2015-07-01T00:00:00Z", 6], + ["2015-08-01T00:00:00Z", 7], + ["2015-08-06T05:20:24.537Z", 0] + ] + }, + { + "key": "# of churned Customers" + "values": [ + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 0], + ["2015-02-01T00:00:00Z", 0], + ["2015-03-01T00:00:00Z", 0], + ["2015-04-01T00:00:00Z", 0], + ["2015-05-01T00:00:00Z", 0], + ["2015-06-01T00:00:00Z", 0], + ["2015-07-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 1], + ["2015-08-06T05:20:24.537Z", 60] + ] + }, + { + "key": "Net New Customers", + "values": [ + ["2014-10-01T00:00:00Z", 2], + ["2014-11-01T00:00:00Z", 2], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 6], + ["2015-02-01T00:00:00Z", 4], + ["2015-03-01T00:00:00Z", 8], + ["2015-04-01T00:00:00Z", 6], + ["2015-05-01T00:00:00Z", 3], + ["2015-06-01T00:00:00Z", 2], + ["2015-07-01T00:00:00Z", 6], + ["2015-08-01T00:00:00Z", 6], + ["2015-08-06T05:20:24.537Z", -60] + ] + } + ], + "extra": [ + { + "key": "% Customer Churn", + "values": [ + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0.0], + ["2014-12-01T00:00:00Z", 0.0], + ["2015-01-01T00:00:00Z", 0.0], + ["2015-02-01T00:00:00Z", 0.0], + ["2015-03-01T00:00:00Z", 0.0], + ["2015-04-01T00:00:00Z", 0.0], + ["2015-05-01T00:00:00Z", 0.0], + ["2015-06-01T00:00:00Z", 0.0], + ["2015-07-01T00:00:00Z", 0.0], + ["2015-08-01T00:00:00Z", 2.08], + ["2015-08-06T05:20:24.537Z", 111.11] + ] + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Metrics" + tags: + - metrics + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/metrics/{organization}/funds/": + get: + operationId: metrics_funds_list + description: |- + Produces sales, payments and refunds over a period of time. + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/cowork/funds/ HTTP/1.1 + + .. code-block:: json + + { + "title": "Amount", + "scale": 0.01, + "unit": "usd", + "table": [ + { + "key": "Total Sales", + "values": [ + ["2014-10-01T00:00:00Z", 1985716], + ["2014-11-01T00:00:00Z", 3516430], + ["2014-12-01T00:00:00Z", 3279451], + ["2015-01-01T00:00:00Z", 3787749], + ["2015-02-01T00:00:00Z", 4480875], + ["2015-03-01T00:00:00Z", 5495920], + ["2015-04-01T00:00:00Z", 7678976], + ["2015-05-01T00:00:00Z", 11064660], + ["2015-06-01T00:00:00Z", 10329043], + ["2015-07-01T00:00:00Z", 11444177], + ["2015-08-01T00:00:00Z", 10274412], + ["2015-08-06T04:59:14.721Z", 14106288] + ] + }, + { + "key": "New Sales", + "values": [ + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 0], + ["2015-02-01T00:00:00Z", 0], + ["2015-03-01T00:00:00Z", 0], + ["2015-04-01T00:00:00Z", 0], + ["2015-05-01T00:00:00Z", 0], + ["2015-06-01T00:00:00Z", 0], + ["2015-07-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 0], + ["2015-08-06T04:59:14.721Z", 0] + ] + }, + { + "key": "Churned Sales", + "values": [ + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 0], + ["2015-02-01T00:00:00Z", 0], + ["2015-03-01T00:00:00Z", 0], + ["2015-04-01T00:00:00Z", 0], + ["2015-05-01T00:00:00Z", 0], + ["2015-06-01T00:00:00Z", 0], + ["2015-07-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 0], + ["2015-08-06T04:59:14.721Z", 0] + ] + }, + { + "key": "Payments", + "values": [ + ["2014-10-01T00:00:00Z", 1787144], + ["2014-11-01T00:00:00Z", 3164787], + ["2014-12-01T00:00:00Z", 2951505], + ["2015-01-01T00:00:00Z", 3408974], + ["2015-02-01T00:00:00Z", 4032787], + ["2015-03-01T00:00:00Z", 4946328], + ["2015-04-01T00:00:00Z", 6911079], + ["2015-05-01T00:00:00Z", 9958194], + ["2015-06-01T00:00:00Z", 9296138], + ["2015-07-01T00:00:00Z", 10299759], + ["2015-08-01T00:00:00Z", 9246970], + ["2015-08-06T04:59:14.721Z", 12695659] + ] + }, + { + "key": "Refunds", + "values": [ + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 0], + ["2015-02-01T00:00:00Z", 0], + ["2015-03-01T00:00:00Z", 0], + ["2015-04-01T00:00:00Z", 0], + ["2015-05-01T00:00:00Z", 0], + ["2015-06-01T00:00:00Z", 0], + ["2015-07-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 0], + ["2015-08-06T04:59:14.721Z", 0] + ] + } + ], + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Metrics" + tags: + - metrics + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/metrics/{organization}/plans/": + get: + operationId: metrics_plans_list + description: |- + Produce plan stats + + **Tags: metrics + + **Examples + + .. code-block:: http + + GET /api/metrics/cowork/plans HTTP/1.1 + + .. code-block:: json + + { + "title": "Active Subscribers", + "table": [ + { + "is_active": true, + "key": "open-space", + "location": "/profile/plan/open-space/", + "values": [ + ["2014-09-01T00:00:00Z", 4], + ["2014-10-01T00:00:00Z", 5], + ["2014-11-01T00:00:00Z", 6], + ["2014-12-01T00:00:00Z", 6], + ["2015-01-01T00:00:00Z", 6], + ["2015-02-01T00:00:00Z", 9], + ["2015-03-01T00:00:00Z", 9], + ["2015-04-01T00:00:00Z", 9], + ["2015-05-01T00:00:00Z", 11], + ["2015-06-01T00:00:00Z", 11], + ["2015-07-01T00:00:00Z", 14], + ["2015-08-01T00:00:00Z", 16], + ["2015-08-06T05:37:50.004Z", 16] + ] + }, + { + "is_active": true, + "key": "open-plus", + "location": "/profile/plan/open-plus/", + "values": [ + ["2014-09-01T00:00:00Z", 7], + ["2014-10-01T00:00:00Z", 8], + ["2014-11-01T00:00:00Z", 9], + ["2014-12-01T00:00:00Z", 9], + ["2015-01-01T00:00:00Z", 12], + ["2015-02-01T00:00:00Z", 13], + ["2015-03-01T00:00:00Z", 18], + ["2015-04-01T00:00:00Z", 19], + ["2015-05-01T00:00:00Z", 19], + ["2015-06-01T00:00:00Z", 20], + ["2015-07-01T00:00:00Z", 23], + ["2015-08-01T00:00:00Z", 25], + ["2015-08-06T05:37:50.014Z", 25] + ] + }, + { + "is_active": true, + "key": "private", + "location": "/profile/plan/private/", + "values": [ + ["2014-09-01T00:00:00Z", 3], + ["2014-10-01T00:00:00Z", 3], + ["2014-11-01T00:00:00Z", 3], + ["2014-12-01T00:00:00Z", 3], + ["2015-01-01T00:00:00Z", 6], + ["2015-02-01T00:00:00Z", 7], + ["2015-03-01T00:00:00Z", 10], + ["2015-04-01T00:00:00Z", 15], + ["2015-05-01T00:00:00Z", 16], + ["2015-06-01T00:00:00Z", 17], + ["2015-07-01T00:00:00Z", 17], + ["2015-08-01T00:00:00Z", 18], + ["2015-08-06T05:37:50.023Z", 18] + ] + } + ], + "extra": [ + { + "key": "churn", + "values": [ + ["2014-09-01T00:00:00Z", 0], + ["2014-10-01T00:00:00Z", 0], + ["2014-11-01T00:00:00Z", 0], + ["2014-12-01T00:00:00Z", 0], + ["2015-01-01T00:00:00Z", 0], + ["2015-02-01T00:00:00Z", 0], + ["2015-03-01T00:00:00Z", 0], + ["2015-04-01T00:00:00Z", 0], + ["2015-05-01T00:00:00Z", 0], + ["2015-06-01T00:00:00Z", 0], + ["2015-07-01T00:00:00Z", 0], + ["2015-08-01T00:00:00Z", 1], + ["2015-08-06T05:37:50.031Z", 1] + ] + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Metrics" + tags: + - metrics + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/notifications/{template}/": + post: + operationId: notifications_create + description: |- + Sends a test notification e-mail. + + **Tags: themes + + **Example + + .. code-block:: http + + POST /api/notifications/contact_requested_notice/ HTTP/1.1 + responses: + "201": + description: "" + tags: + - notifications + parameters: + - name: template + in: path + required: true + schema: + type: string + example: contact_requested_notice + /profile/: + get: + operationId: profile_list + description: >- + Queries a page (``PAGE_SIZE`` records) of organization and user + profiles. + + + The queryset can be filtered for at least one field to match a search + + term (``q``). + + + The queryset can be ordered by a field by adding an HTTP query parameter + + ``o=`` followed by the field name. A sequence of fields can be used + + to create a complete ordering by adding a sequence of ``o`` HTTP query + + parameters. To reverse the natural order of a field, prefix the field + + name by a minus (-) sign. + + + **Tags: profile + + + **Examples + + + .. code-block:: http + + GET /api/profile/?o=created_at HTTP/1.1 + + responds + + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [{ + "slug": "xia", + "full_name": "Xia Lee", + "printable_name": "Xia Lee", + "created_at": "2016-01-14T23:16:55Z" + }] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in slug, full_name, email, phone, + street_address, locality, region, postal_code, country, username, + first_name, last_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by u, r + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Organization" + tags: + - profile + post: + operationId: profile_create + description: |- + Creates an organization, personal or user profile. + + **Examples + + .. code-block:: http + + POST /api/profile/ HTTP/1.1 + + .. code-block:: json + + { + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationCreate" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationCreate" + tags: + - profile + parameters: [] + "/profile/{organization}/": + get: + operationId: profile_read + description: |- + Retrieves an organization, personal or user profile. + + **Tags: profile + + **Examples + + .. code-block:: http + + GET /api/profile/xia/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "printable_name": "Xia Lee", + "slug": "xia", + "subscriptions": [ + { + "created_at": "2018-01-01T00:00:00Z", + "ends_at": "2019-01-01T00:00:00Z", + "plan": "open-space", + "auto_renew": true + } + ] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationWithSubscriptions" + tags: + - profile + put: + operationId: profile_update + description: |- + Updates an organization, personal or user profile. + + **Examples + + .. code-block:: http + + PUT /api/profile/xia/ HTTP/1.1 + + .. code-block:: json + + { + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee" + } + requestBody: + $ref: "#/components/requestBodies/OrganizationWithSubscriptions" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationWithSubscriptions" + tags: + - profile + patch: + operationId: profile_partial_update + description: |- + Retrieves an organization, personal or user profile. + + **Tags: profile + + **Examples + + .. code-block:: http + + GET /api/profile/xia/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "printable_name": "Xia Lee", + "slug": "xia", + "subscriptions": [ + { + "created_at": "2018-01-01T00:00:00Z", + "ends_at": "2019-01-01T00:00:00Z", + "plan": "open-space", + "auto_renew": true + } + ] + } + requestBody: + $ref: "#/components/requestBodies/OrganizationWithSubscriptions" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationWithSubscriptions" + tags: + - profile + delete: + operationId: profile_delete + description: |- + Deletes a profile. + + We anonymize the organization instead of purely deleting + it from the database because we don't want to loose history + on subscriptions and transactions. + + **Tags: profile + + **Examples + + .. code-block:: http + + DELETE /api/profile/xia/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: xia + "/profile/{organization}/plans/": + get: + operationId: profile_plans_list + description: |- + Create a ``Plan`` for a provider. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + POST /api/profile/cowork/plans HTTP/1.1 + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + + responds + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: o + in: query + description: sort by title, period_amount, is_active, created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Plan" + tags: + - profile + post: + operationId: profile_plans_create + description: |- + Create a ``Plan`` for a provider. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + POST /api/profile/cowork/plans HTTP/1.1 + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + + responds + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + requestBody: + $ref: "#/components/requestBodies/Plan" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Plan" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/profile/{organization}/plans/{plan}/": + get: + operationId: profile_plans_read + description: >- + Retrieves a ``Plan``. + + + The ``is_active`` boolean is used to activate a plan, enabling users + + to subscribe to it, or deactivate a plan, disabling users from subscribing + + to it. + + + **Tags: subscriptions + + + **Examples + + + .. code-block:: http + + GET /api/profile/cowork/plans/open-space HTTP/1.1 + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Plan" + tags: + - profile + put: + operationId: profile_plans_update + description: |- + Updates a ``Plan``. + + The ``is_active`` boolean is used to activate a plan, enabling users + to subscribe to it, or deactivate a plan, disabling users + from subscribing to it. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + PUT /api/profile/cowork/plans/open-space HTTP/1.1 + + .. code-block:: json + + { + "title": "Open Space", + } + + responds + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + requestBody: + $ref: "#/components/requestBodies/Plan" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Plan" + tags: + - profile + patch: + operationId: profile_plans_partial_update + description: >- + Retrieves a ``Plan``. + + + The ``is_active`` boolean is used to activate a plan, enabling users + + to subscribe to it, or deactivate a plan, disabling users from subscribing + + to it. + + + **Tags: subscriptions + + + **Examples + + + .. code-block:: http + + GET /api/profile/cowork/plans/open-space HTTP/1.1 + + .. code-block:: json + + { + "title": "Open Space", + "description": "A desk in our coworking space", + "is_active": false, + "period_amount": 12000, + "interval": 1 + } + requestBody: + $ref: "#/components/requestBodies/Plan" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Plan" + tags: + - profile + delete: + operationId: profile_plans_delete + description: |- + Deletes a ``Plan``. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + DELETE /api/profile/cowork/plans/open-space HTTP/1.1 + responses: + "204": + description: "" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: plan + in: path + required: true + schema: + type: string + example: open-space + "/profile/{organization}/plans/{plan}/subscriptions/": + get: + operationId: profile_plans_subscriptions_list + description: |- + A GET request will list all ``Subscription`` to + a specified ``:plan`` provided by ``:organization``. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/plans/premium/subscriptions/ HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "slug": "xia", + "full_name": "Xia Lee", + "created_at": "2016-01-14T23:16:55Z" + } + ] + } + parameters: + - name: o + in: query + description: sort by organization, plan, created_at, ends_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in organization__slug, + organization__full_name, organization__email, organization__phone, + organization__street_address, organization__locality, + organization__region, organization__postal_code, + organization__country, plan__title + required: false + schema: + type: string + example: query + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Subscription" + tags: + - profile + post: + operationId: profile_plans_subscriptions_create + description: |- + A POST request will subscribe an organization to the ``:plan``. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + POST /api/profile/cowork/plans/premium/subscriptions/ HTTP/1.1 + + .. code-block:: json + + { + "organization": { + "slug": "xia" + } + } + + responds + + .. code-block:: json + + { + "created_at": "2016-01-14T23:16:55Z", + "ends_at": "2017-01-14T23:16:55Z", + "description": null, + "organization": { + "slug": "xia", + "printable_name": "Xia Lee" + }, + "plan": { + "slug": "open-space", + "title": "Open Space", + "description": "open space desk, High speed internet + - Ethernet or WiFi, Unlimited printing, + Unlimited scanning, Unlimited fax service + (send and receive)", + "is_active": true, + "setup_amount": 0, + "period_amount": 17999, + "interval": 4, + "app_url": "http://localhost:8020/app" + }, + "auto_renew": true + } + parameters: + - name: force + in: query + description: Forces invite of user/organization that could not be found + required: false + schema: + type: boolean + example: true + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionCreate" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/SubscriptionCreate" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: plan + in: path + required: true + schema: + type: string + example: premium + "/profile/{organization}/plans/{plan}/subscriptions/{subscriber}/": + get: + operationId: profile_plans_subscriptions_read + description: |- + Unsubscribe an organization from a plan. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + + .. code-block:: json + + { + ... XXX ... + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + put: + operationId: profile_plans_subscriptions_update + description: |- + Updates an organization subscription. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + PUT /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + + .. code-block:: json + + { + ... XXX ... + } + + responds + + .. code-block:: json + + { + ... XXX ... + } + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + patch: + operationId: profile_plans_subscriptions_partial_update + description: |- + Unsubscribe an organization from a plan. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + + .. code-block:: json + + { + ... XXX ... + } + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + delete: + operationId: profile_plans_subscriptions_delete + description: >- + Unsubscribe an organization from a plan. + + + **Tags: subscriptions + + + **Examples + + + .. code-block:: http + + DELETE /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: plan + in: path + required: true + schema: + type: string + example: open-space + - name: subscriber + in: path + required: true + schema: + type: string + example: xia + "/profile/{organization}/roles/": + get: + operationId: profile_roles_list + description: |- + Lists all roles for an organization + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/roles/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "role_description": { + "name": "Manager", + "slug": "manager", + "organization": { + "slug": "cowork", + "full_name": "ABC Corp.", + "printable_name": "ABC Corp.", + "created_at": "2018-01-01T00:00:00Z", + "email": "support@localhost.localdomain" + } + }, + "user": { + "slug": "alice", + "email": "alice@localhost.localdomain", + "full_name": "Alice Doe", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": "1", + "grant_key": null + }, + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in organization__slug, + organization__full_name, organization__email, user__username, + user__email, role_description__title, role_description__slug + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by full_name, username, role_name, grant_key, request_key, + created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Role" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/profile/{organization}/roles/describe/": + get: + operationId: profile_roles_describe_list + description: |- + Lists roles by description``RoleDescription``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/roles/describe/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "title": "Managers", + "slug": "manager", + "is_global": true, + "roles": [ + { + "created_at": "2018-01-01T00:00:00Z", + "user": { + "slug": "donny", + "email": "donny@localhost.localdomain", + "full_name": "Donny Cooper", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": null, + "grant_key": null + }, + ] + }, + { + "created_at": "2018-01-01T00:00:00Z", + "name": "Contributors", + "slug": "contributor", + "is_global": false, + "roles": [] + } + ] + } + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/RoleDescriptionCRUD" + tags: + - profile + post: + operationId: profile_roles_describe_create + description: |- + Creates a new role that users can take on an organization. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/roles/describe/ HTTP/1.1 + + .. code-block:: json + + { + "title": "Managers", + } + + responds + + .. code-block:: json + + { + "count": 2, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "name": "Managers", + "slug": "manager", + "is_global": true, + "roles": [ + { + "created_at": "2018-01-01T00:00:00Z", + "user": { + "slug": "donny", + "email": "donny@localhost.localdomain", + "full_name": "Donny Cooper", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": null, + "grant_key": null + }, + ] + }, + { + "created_at": "2018-01-01T00:00:00Z", + "name": "Contributors", + "slug": "contributor", + "is_global": false, + "roles": [] + } + ] + } + requestBody: + $ref: "#/components/requestBodies/RoleDescriptionCRUD" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RoleDescriptionCRUD" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/profile/{organization}/roles/describe/{role}/": + get: + operationId: profile_roles_describe_read + description: |- + Retrieves a ``RoleDescription``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/roles/describe/manager HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "name": "Managers", + "slug": "manager", + "is_global": true, + "roles": [ + { + "created_at": "2018-01-01T00:00:00Z", + "user": { + "slug": "donny", + "email": "donny@localhost.localdomain", + "full_name": "Donny Cooper", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": null, + "grant_key": null + }, + ] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RoleDescriptionCRUD" + tags: + - profile + put: + operationId: profile_roles_describe_update + description: |- + Updates ``RoleDescription``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/profile/cowork/roles/describe/manager HTTP/1.1 + + .. code-block:: json + + { + "title": "Profile managers" + } + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "title": "Profile managers", + "slug": "manager", + "is_global": true, + "roles": [ + { + "created_at": "2018-01-01T00:00:00Z", + "user": { + "slug": "donny", + "email": "donny@localhost.localdomain", + "full_name": "Donny Cooper", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": null, + "grant_key": null + }, + ] + } + requestBody: + $ref: "#/components/requestBodies/RoleDescriptionCRUD" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RoleDescriptionCRUD" + tags: + - profile + patch: + operationId: profile_roles_describe_partial_update + description: |- + Retrieves a ``RoleDescription``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/roles/describe/manager HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "name": "Managers", + "slug": "manager", + "is_global": true, + "roles": [ + { + "created_at": "2018-01-01T00:00:00Z", + "user": { + "slug": "donny", + "email": "donny@localhost.localdomain", + "full_name": "Donny Cooper", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": null, + "grant_key": null + }, + ] + } + requestBody: + $ref: "#/components/requestBodies/RoleDescriptionCRUD" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RoleDescriptionCRUD" + tags: + - profile + delete: + operationId: profile_roles_describe_delete + description: |- + Deletes ``RoleDescription``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + DELETE /api/profile/cowork/roles/describe/manager HTTP/1.1 + responses: + "204": + description: "" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: role + in: path + required: true + schema: + type: string + example: manager + "/profile/{organization}/roles/{role}/": + get: + operationId: profile_roles_read + description: |- + ``GET`` lists the specified role assignments for an organization. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/roles/manager/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "role_description": { + "name": "Manager", + "slug": "manager", + "organization": { + "slug": "cowork", + "full_name": "ABC Corp.", + "printable_name": "ABC Corp.", + "created_at": "2018-01-01T00:00:00Z", + "email": "support@localhost.localdomain" + } + }, + "user": { + "slug": "alice", + "email": "alice@localhost.localdomain", + "full_name": "Alice Doe", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": "1", + "grant_key": null + }, + ] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Role" + tags: + - profile + post: + operationId: profile_roles_create + description: |- + Attaches a user to a role on an organization, typically granting + permissions to the user with regards to managing an organization profile + (see :doc:`Flexible Security Framework `). + + **Tags: rbac + + **Examples + + .. code-block:: http + + POST /api/profile/cowork/roles/manager/ HTTP/1.1 + + .. code-block:: json + + { + "slug": "xia" + } + + responds + + .. code-block:: json + + { + "slug": "xia" + } + parameters: + - name: force + in: query + description: Forces invite of user/organization that could not be found + required: false + schema: + type: boolean + example: true + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/UserRoleCreate" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/UserRoleCreate" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: role + in: path + required: true + schema: + type: string + example: manager + "/profile/{organization}/roles/{role}/{user}/": + post: + operationId: profile_roles_resend_email + description: |- + Re-sends the invite e-mail that the user was granted a role + on the organization. + + **Tags: rbac + + **Examples + + .. code-block:: http + + POST /api/profile/cowork/roles/manager/xia/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "role_description": { + "created_at": "2018-01-01T00:00:00Z", + "title": "Profile Manager", + "slug": "manager", + "is_global": true, + "organization": { + "slug": "cowork", + "full_name": "ABC Corp.", + "printable_name": "ABC Corp.", + "created_at": "2018-01-01T00:00:00Z", + "email": "support@localhost.localdomain" + } + }, + "user": { + "slug": "alice", + "email": "alice@localhost.localdomain", + "full_name": "Alice Doe", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": "1", + "grant_key": null + } + requestBody: + $ref: "#/components/requestBodies/RoleAccessible" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RoleAccessible" + tags: + - profile + delete: + operationId: profile_roles_delete + description: |- + Dettach a user from one or all roles with regards to an organization, + typically resulting in revoking permissions from this user to manage + part of an organization profile. + + **Tags: rbac + + **Examples + + .. code-block:: http + + DELETE /api/profile/cowork/roles/managers/xia/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: role + in: path + required: true + schema: + type: string + example: manager + - name: user + in: path + required: true + schema: + type: string + example: xia + "/profile/{organization}/subscribers/": + get: + operationId: profile_subscribers_list + description: |- + List all ``Organization`` which have or had a subscription to a plan + provided by ``:organization``. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/subscribers/?o=created_at&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "slug": "xia", + "full_name": "Xia Lee", + "created_at": "2016-01-14T23:16:55Z" + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in slug, full_name, email, phone, + street_address, locality, region, postal_code, country, username, + first_name, last_name + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by u, r + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Organization" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + "/profile/{organization}/subscribers/accept/{request_key}/": + put: + operationId: profile_subscribers_accept_update + description: |- + Accepts a subscription request. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/profile/xia/subscribers/accept/abcdef12 HTTP/1.1 + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + patch: + operationId: profile_subscribers_accept_partial_update + description: "" + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: xia + - name: request_key + in: path + required: true + schema: + type: string + example: abcdef12 + "/profile/{organization}/subscriptions/": + get: + operationId: profile_subscriptions_list + description: >- + GET queries all ``Subscription`` of an ``Organization``. The queryset + + can be further refined to match a search filter (``q``) and sorted + + on a specific field. The returned queryset is always paginated. + + + **Tags: subscriptions + + + **Examples + + + .. code-block:: http + + GET /api/profile/:organization/subscriptions/?o=created_at&ot=desc HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2016-01-14T23:16:55Z", + "ends_at": "2017-01-14T23:16:55Z", + "description": null, + "organization": { + "slug": "xia", + "printable_name": "Xia Lee" + }, + "plan": { + "slug": "open-space", + "title": "Open Space", + "description": "open space desk, High speed internet + - Ethernet or WiFi, Unlimited printing, + Unlimited scanning, Unlimited fax service + (send and receive)", + "is_active": true, + "setup_amount": 0, + "period_amount": 17999, + "interval": 4, + "app_url": "http://localhost:8020/app" + }, + "auto_renew": true + } + ] + } + parameters: + - name: o + in: query + description: sort by organization, plan, created_at, ends_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: q + in: query + description: search for matching text in organization__slug, + organization__full_name, organization__email, organization__phone, + organization__street_address, organization__locality, + organization__region, organization__postal_code, + organization__country, plan__title + required: false + schema: + type: string + example: query + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Subscription" + tags: + - profile + post: + operationId: profile_subscriptions_create + description: |- + Subscribes the organization to a plan. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + POST /api/profile/:organization/subscriptions/ HTTP/1.1 + + .. code-block:: json + + { + "plan": "open-space" + } + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: xia + "/profile/{organization}/subscriptions/{subscribed_plan}/": + get: + operationId: profile_subscriptions_read + description: |- + Retrieves a ``Subscription``. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + + .. code-block:: json + + { + ... XXX ... + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + put: + operationId: profile_subscriptions_update + description: |- + Updates an organization subscription. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + PUT /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + + .. code-block:: json + + { + ... XXX ... + } + + responds + + .. code-block:: json + + { + ... XXX ... + } + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + patch: + operationId: profile_subscriptions_partial_update + description: |- + Retrieves a ``Subscription``. + + **Tags: subscriptions + + **Examples + + .. code-block:: http + + GET /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + + .. code-block:: json + + { + ... XXX ... + } + requestBody: + $ref: "#/components/requestBodies/Subscription" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + tags: + - profile + delete: + operationId: profile_subscriptions_delete + description: >- + Unsubscribe an organization from a plan. + + + **Tags: subscriptions + + + **Examples + + + .. code-block:: http + + DELETE /api/profile/cowork/plans/open-space/subscriptions/xia/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - profile + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: subscribed_plan + in: path + required: true + schema: + type: string + example: open-space + /proxy/: + get: + operationId: proxy_read + description: |- + Returns the URL endpoint to which requests passing the access rules + are forwarded to, and the format in which the session information + is encoded. + + When running tests, you can retrieve the actual session information + for a specific user through the `/proxy/sessions/{user}/` API call. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "slug": "cowork", + "entry_point": "http://localhost:8001/", + "session_backend": 1 + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/App" + tags: + - proxy + put: + operationId: proxy_update + description: |- + Updates the URL endpoint to which requests passing the access rules + are forwarded to and/or the format in which the session information + is encoded. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/proxy/ HTTP/1.1 + + .. code-block:: json + + { + "entry_point": "http://localhost:8001/", + "session_backend": 1 + } + + responds + + .. code-block:: json + + { + "slug": "cowork", + "entry_point": "http://localhost:8001/", + "session_backend": 1 + } + requestBody: + $ref: "#/components/requestBodies/App" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/App" + tags: + - proxy + patch: + operationId: proxy_partial_update + description: |- + Returns the URL endpoint to which requests passing the access rules + are forwarded to, and the format in which the session information + is encoded. + + When running tests, you can retrieve the actual session information + for a specific user through the `/proxy/sessions/{user}/` API call. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "slug": "cowork", + "entry_point": "http://localhost:8001/", + "session_backend": 1 + } + requestBody: + $ref: "#/components/requestBodies/App" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/App" + tags: + - proxy + parameters: [] + /proxy/engagement/: + get: + operationId: proxy_engagement_list + description: "" + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Engagements" + tags: + - proxy + parameters: [] + /proxy/engagement/users/: + get: + operationId: proxy_engagement_users_list + description: "" + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/UserEngagement" + tags: + - proxy + parameters: [] + /proxy/key/: + put: + operationId: proxy_key_update + description: |- + Rotates the key used to encode the session information forwarded + to the application entry point. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/proxy/key/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "enc_key": "********", + } + requestBody: + $ref: "#/components/requestBodies/AppKey" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/AppKey" + tags: + - proxy + patch: + operationId: proxy_key_partial_update + description: |- + Rotates the key used to encode the session information forwarded + to the application entry point. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/proxy/key/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "enc_key": "********", + } + requestBody: + $ref: "#/components/requestBodies/AppKey" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/AppKey" + tags: + - proxy + parameters: [] + /proxy/recent/: + get: + operationId: proxy_recent_list + description: "" + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Activity" + tags: + - proxy + parameters: [] + /proxy/rules: + get: + operationId: proxy_rules_list + description: |- + Queries a page (``PAGE_SIZE`` records) of ``Rule``. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/rules/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "rank": 0, + "path": "/", + "allow": "authenticated", + "is_forward": true, + "engaged": "" + } + ] + } + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Rule" + tags: + - proxy + post: + operationId: proxy_rules_create + description: |- + Creates a new ``Rule``. + + **Tags: rbac + + **Examples + + .. code-block:: http + + POST /api/proxy/rules/ HTTP/1.1 + + .. code-block:: json + + { + "rank": 0, + "path": "/", + "allow": "authenticated", + "is_forward": true, + "engaged": "" + } + requestBody: + $ref: "#/components/requestBodies/Rule" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Rule" + tags: + - proxy + patch: + operationId: proxy_rules_partial_update + description: |- + Update the rank of rules. + + When receiving a request like [{u'newpos': 1, u'oldpos': 3}], + it will move the rule at position 3 to position 1, updating all + rules ranks in-between. + + **Tags: rbac + requestBody: + $ref: "#/components/requestBodies/Rule" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Rule" + tags: + - proxy + parameters: [] + "/proxy/rules{rule}": + get: + operationId: proxy_rule_read + description: |- + Retrieves details on a ``Rule``. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/rules/app/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "rank": 0, + "path": "/app/", + "allow": "authenticated", + "is_forward": true, + "engaged": "" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateRule" + tags: + - proxy + put: + operationId: proxy_rule_update + description: |- + Updates a ``Rule``. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/proxy/rules/app/ HTTP/1.1 + + .. code-block:: json + + { + "rank": 0, + "path": "/app/", + "allow": "authenticated", + "is_forward": true, + "engaged": "" + } + + responds + + .. code-block:: json + + { + "rank": 0, + "path": "/app/", + "allow": "authenticated", + "is_forward": true, + "engaged": "" + } + requestBody: + $ref: "#/components/requestBodies/UpdateRule" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateRule" + tags: + - proxy + patch: + operationId: proxy_rule_partial_update + description: |- + Retrieves details on a ``Rule``. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/rules/app/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "rank": 0, + "path": "/app/", + "allow": "authenticated", + "is_forward": true, + "engaged": "" + } + requestBody: + $ref: "#/components/requestBodies/UpdateRule" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateRule" + tags: + - proxy + delete: + operationId: proxy_delete + description: |- + Deletes a ``Rule``. + + **Tags: rbac + + **Examples + + .. code-block:: http + + DELETE /api/proxy/rules/app/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - proxy + parameters: + - name: rule + in: path + required: true + schema: + type: string + example: app + "/proxy/sessions/{user}/": + get: + operationId: proxy_sessions_read + description: |- + Returns a session data for a user as it will be passed to the backend + service. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/proxy/sessions/xia/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "forward_session": "{username: xia}", + "forward_session_header": "Authorization: XXX", + "forward_url": "http://localhost:8001/" + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/SessionData" + tags: + - proxy + parameters: + - name: user + in: path + required: true + schema: + type: string + example: xia + /themes/: + post: + operationId: themes_create + description: >- + Uploads a theme package with templates that will override the default + + ones. See `references and tutorials on creating themes + + `_ for details on the theme package + + structure and customizing the default templates. + + + **Tags: themes + + + **Examples + + + .. code-block:: shell + + curl -i -u *api_key*: -X POST -F file=@*package*.zip https://*mydomain*/api/themes/ + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/ThemePackageUploadBody" + required: true + responses: + "200": + description: Upload successful + content: + application/json: + schema: + $ref: "#/components/schemas/ThemePackageUpload" + tags: + - themes + delete: + operationId: themes_delete + description: |- + Removes the custom theme templates and assets. + + Pages will be using the default theme after a reset. + + **Tags: themes + + **Examples + + .. code-block:: http + + DELETE /api/themes HTTP/1.1 + responses: + "204": + description: "" + tags: + - themes + parameters: [] + "/themes/assets{path}/": + get: + operationId: themes_read + description: |- + Lists static asset files. + + **Examples + + .. code-block:: http + + GET /api/assets/ HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + results: [{ + "location": "/media/image-001.jpg", + "updated_at": "2016-10-26T00:00:00.00000+00:00", + "tags": [] + }] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Asset" + tags: + - themes + post: + operationId: themes_assets_create + description: |- + Uploads a static asset file. + + **Examples + + .. code-block:: http + + POST /api/assets/ HTTP/1.1 + requestBody: + $ref: "#/components/requestBodies/Asset" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Asset" + tags: + - themes + put: + operationId: themes_update + description: |- + Updates meta tags on assets. + + **Examples + + .. code-block:: http + + PUT /api/assets/ HTTP/1.1 + + .. code-block:: json + + { + items: [ + {location: "/media/item/url1.jpg"}, + {location: "/media/item/url2.jpg"}, + .... + ], + tags: ['photo', 'homepage'] + } + + When the API returns, both assets file listed in items will be tagged + with 'photo' and 'homepage'. Those tags can then be used later on + in searches. + requestBody: + $ref: "#/components/requestBodies/Asset" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Asset" + tags: + - themes + delete: + operationId: themes_assets_delete + description: |- + Deletes static assets file + + **Examples + + .. code-block:: http + + DELETE /api/assets/ HTTP/1.1 + + .. code-block:: json + + { + items: [ + {location: "/media/item/url1.jpg"}, + {location: "/media/item/url2.jpg"}, + .... + ] + } + responses: + "204": + description: "" + tags: + - themes + parameters: + - name: path + in: path + required: true + schema: + type: string + example: "TODO" + /themes/editables/: + get: + operationId: themes_editables_list + description: "" + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/PageElement" + tags: + - themes + post: + operationId: themes_editables_create + description: "" + requestBody: + $ref: "#/components/requestBodies/PageElement" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElement" + tags: + - themes + parameters: [] + "/themes/editables/alias{path}/": + post: + operationId: themes_editables_alias_create + description: Alias the content of a PageElement at another node. + requestBody: + $ref: "#/components/requestBodies/EdgeCreate" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/EdgeCreate" + tags: + - themes + parameters: + - name: path + in: path + required: true + schema: + type: string + example: "TODO" + "/themes/editables/attach{path}": + post: + operationId: themes_editables_attach_create + description: Move an PageElement from one attachement to another. + requestBody: + $ref: "#/components/requestBodies/EdgeCreate" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/EdgeCreate" + tags: + - themes + parameters: + - name: path + in: path + required: true + schema: + type: string + example: "TODO" + "/themes/editables/mirror{path}/": + post: + operationId: themes_editables_mirror_create + description: |- + Mirror the content of a PageElement and attach the mirror + under another node. + requestBody: + $ref: "#/components/requestBodies/EdgeCreate" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/EdgeCreate" + tags: + - themes + parameters: + - name: path + in: path + required: true + schema: + type: string + example: "TODO" + /themes/editables/relationship/: + get: + operationId: themes_editables_relationship_list + description: "" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RelationShip" + tags: + - themes + post: + operationId: themes_editables_relationship_create + description: "" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/RelationShip" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RelationShip" + tags: + - themes + delete: + operationId: themes_editables_relationship_delete + description: "" + responses: + "204": + description: "" + tags: + - themes + parameters: [] + "/themes/editables/{slug}/": + get: + operationId: themes_editables_read + description: Create or Update an editable element on a ``PageElement``. + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElement" + tags: + - themes + put: + operationId: themes_editables_update + description: Create or Update an editable element on a ``PageElement``. + requestBody: + $ref: "#/components/requestBodies/PageElement" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElement" + tags: + - themes + patch: + operationId: themes_editables_partial_update + description: Create or Update an editable element on a ``PageElement``. + requestBody: + $ref: "#/components/requestBodies/PageElement" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElement" + tags: + - themes + delete: + operationId: themes_editables_delete + description: Create or Update an editable element on a ``PageElement``. + responses: + "204": + description: "" + tags: + - themes + parameters: + - name: slug + in: path + required: true + schema: + type: string + example: "TODO" + "/themes/editables/{slug}/add-tags/": + put: + operationId: themes_editables_add-tags_update + description: |- + Add tags to a ``PageElement`` if they are not already present. + + **Tags: themes + + **Example + + .. sourcecode:: http + + PUT /api/editables/_my-element_/add-tags + + .. sourcecode:: json + + { + "tag": "sometag" + } + + .. sourcecode:: json + + { + } + requestBody: + $ref: "#/components/requestBodies/PageElementTag" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElementTag" + tags: + - themes + patch: + operationId: themes_editables_add-tags_partial_update + description: |- + Add tags to a ``PageElement`` if they are not already present. + + **Tags: themes + + **Example + + .. sourcecode:: http + + PUT /api/editables/_my-element_/add-tags + + .. sourcecode:: json + + { + "tag": "sometag" + } + + .. sourcecode:: json + + { + } + requestBody: + $ref: "#/components/requestBodies/PageElementTag" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElementTag" + tags: + - themes + parameters: + - name: slug + in: path + required: true + schema: + type: string + example: "TODO" + "/themes/editables/{slug}/remove-tags/": + put: + operationId: themes_editables_remove-tags_update + description: |- + Remove tags from a ``PageElement``. + + **Tags: themes + + **Examples + + .. sourcecode:: http + + PUT /api/editables/_my-element_/reomve-tags + + .. sourcecode:: json + + { + "tag": "sometag" + } + + **Examples + + .. sourcecode:: json + + { + } + requestBody: + $ref: "#/components/requestBodies/PageElementTag" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElementTag" + tags: + - themes + patch: + operationId: themes_editables_remove-tags_partial_update + description: |- + Remove tags from a ``PageElement``. + + **Tags: themes + + **Examples + + .. sourcecode:: http + + PUT /api/editables/_my-element_/reomve-tags + + .. sourcecode:: json + + { + "tag": "sometag" + } + + **Examples + + .. sourcecode:: json + + { + } + requestBody: + $ref: "#/components/requestBodies/PageElementTag" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PageElementTag" + tags: + - themes + parameters: + - name: slug + in: path + required: true + schema: + type: string + example: "TODO" + /themes/sitecss: + get: + operationId: themes_sitecss_list + description: "" + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Asset" + tags: + - themes + post: + operationId: themes_sitecss_create + description: |- + Uploads a static asset file. + + **Examples + + .. code-block:: http + + POST /api/assets/ HTTP/1.1 + requestBody: + $ref: "#/components/requestBodies/Asset" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Asset" + tags: + - themes + put: + operationId: themes_sitecss_update + description: |- + Updates meta tags on assets. + + **Examples + + .. code-block:: http + + PUT /api/assets/ HTTP/1.1 + + .. code-block:: json + + { + items: [ + {location: "/media/item/url1.jpg"}, + {location: "/media/item/url2.jpg"}, + .... + ], + tags: ['photo', 'homepage'] + } + + When the API returns, both assets file listed in items will be tagged + with 'photo' and 'homepage'. Those tags can then be used later on + in searches. + requestBody: + $ref: "#/components/requestBodies/Asset" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Asset" + tags: + - themes + delete: + operationId: themes_sitecss_delete + description: |- + Deletes static assets file + + **Examples + + .. code-block:: http + + DELETE /api/assets/ HTTP/1.1 + + .. code-block:: json + + { + items: [ + {location: "/media/item/url1.jpg"}, + {location: "/media/item/url2.jpg"}, + .... + ] + } + responses: + "204": + description: "" + tags: + - themes + parameters: [] + /themes/sitecss/variables/: + get: + operationId: themes_sitecss_variables_list + description: "" + parameters: + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/LessVariable" + tags: + - themes + put: + operationId: themes_sitecss_variables_update + description: "" + requestBody: + $ref: "#/components/requestBodies/LessVariable" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/LessVariable" + tags: + - themes + parameters: [] + "/themes/sitecss/variables/{name}/": + get: + operationId: themes_sitecss_variables_read + description: Create or update the value of a ``LessVariable``. + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/LessVariable" + tags: + - themes + put: + operationId: themes_sitecss_variables_var_update + description: Create or update the value of a ``LessVariable``. + requestBody: + $ref: "#/components/requestBodies/LessVariable" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/LessVariable" + tags: + - themes + patch: + operationId: themes_sitecss_variables_partial_update + description: Create or update the value of a ``LessVariable``. + requestBody: + $ref: "#/components/requestBodies/LessVariable" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/LessVariable" + tags: + - themes + delete: + operationId: themes_sitecss_variables_delete + description: Create or update the value of a ``LessVariable``. + responses: + "204": + description: "" + tags: + - themes + parameters: + - name: name + in: path + required: true + schema: + type: string + example: "TODO" + "/themes/sources/{page}": + get: + operationId: themes_sources_read + description: "" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/SourceCode" + tags: + - themes + post: + operationId: themes_sources_create + description: "" + requestBody: + $ref: "#/components/requestBodies/SourceCode" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/SourceCode" + tags: + - themes + put: + operationId: themes_sources_update + description: "" + requestBody: + $ref: "#/components/requestBodies/SourceCode" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/SourceCode" + tags: + - themes + patch: + operationId: themes_sources_partial_update + description: "" + requestBody: + $ref: "#/components/requestBodies/SourceCode" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/SourceCode" + tags: + - themes + parameters: + - name: page + in: path + required: true + schema: + type: string + example: "TODO" + /users/: + get: + operationId: users_list + description: >- + Queries a page (``PAGE_SIZE`` records) of organization and user + profiles. + + + The queryset can be filtered for at least one field to match a search + + term (``q``). + + + The queryset can be ordered by a field by adding an HTTP query parameter + + ``o=`` followed by the field name. A sequence of fields can be used + + to create a complete ordering by adding a sequence of ``o`` HTTP query + + parameters. To reverse the natural order of a field, prefix the field + + name by a minus (-) sign. + + + **Tags: profile + + + **Example + + + .. code-block:: http + + GET /api/users/?q=xia HTTP/1.1 + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [{ + "slug": "xia", + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "nick_name": "Xia", + "created_at": "2018-01-01T00:00:00Z", + "activities": [{ + "created_at": "2018-01-01T00:00:00Z", + "created_by": "alice", + "text": "Phone call", + "account": null + },{ + "created_at": "2018-01-02T00:00:00Z", + "created_by": "alice", + "text": "Follow up e-mail", + "account": "cowork" + }] + }] + } + parameters: + - name: q + in: query + description: A search term. + required: false + schema: + type: string + example: query + - name: o + in: query + description: Which field to use when ordering the results. + required: false + schema: + type: string + example: created_at + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Contact" + tags: + - users + post: + operationId: users_create + description: |- + Creates a new user profile. + + **Tags: profile + + **Examples + + .. code-block:: http + + POST /api/users/ HTTP/1.1 + + .. code-block:: json + + { + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "nick_name": "Xia" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/Contact" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Contact" + tags: + - users + parameters: [] + "/users/{user}/": + get: + operationId: users_read + description: |- + Retrieves details on one single user profile with slug ``{user}``. + + **Tags: profile + + **Examples + + .. code-block:: http + + GET /api/users/xia HTTP/1.1 + + .. code-block:: json + + { + "slug": "xia", + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "nick_name": "Xia", + "created_at": "2018-01-01T00:00:00Z", + "activities": [{ + "created_at": "2018-01-01T00:00:00Z", + "created_by": "alice", + "text": "Phone call", + "account": null + },{ + "created_at": "2018-01-02T00:00:00Z", + "created_by": "alice", + "text": "Follow up e-mail", + "account": "cowork" + }] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/ContactDetail" + tags: + - users + put: + operationId: users_update + description: |- + Updates a user profile. + + **Tags: profile + + **Examples + + .. code-block:: http + + PUT /api/users/xia/ HTTP/1.1 + + .. code-block:: json + + { + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "nick_name": "Xia", + } + requestBody: + $ref: "#/components/requestBodies/ContactDetail" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/ContactDetail" + tags: + - users + patch: + operationId: users_partial_update + description: |- + Retrieves details on one single user profile with slug ``{user}``. + + **Tags: profile + + **Examples + + .. code-block:: http + + GET /api/users/xia HTTP/1.1 + + .. code-block:: json + + { + "slug": "xia", + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "nick_name": "Xia", + "created_at": "2018-01-01T00:00:00Z", + "activities": [{ + "created_at": "2018-01-01T00:00:00Z", + "created_by": "alice", + "text": "Phone call", + "account": null + },{ + "created_at": "2018-01-02T00:00:00Z", + "created_by": "alice", + "text": "Follow up e-mail", + "account": "cowork" + }] + } + requestBody: + $ref: "#/components/requestBodies/ContactDetail" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/ContactDetail" + tags: + - users + delete: + operationId: users_delete + description: |- + Deletes a user profile. + + **Tags: profile + + **Examples + + .. code-block:: http + + DELETE /api/users/xia/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: xia + "/users/{user}/accessibles/": + get: + operationId: users_accessibles_list + description: |- + Lists all relations where an ``Organization`` is accessible by + a ``User``. Typically the user was granted specific permissions through + a ``Role``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/users/alice/accessibles/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "slug": "cowork", + "printable_name": "ABC Corp.", + "role_description": "manager", + "request_key": null, + "grant_key": null + } + ] + } + parameters: + - name: start_at + in: query + description: date/time in ISO format after which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: ends_at + in: query + description: date/time in ISO format before which records were created. + required: false + schema: + type: string + example: "2014-01-01T00:00:00Z" + - name: q + in: query + description: search for matching text in organization__slug, + organization__full_name, organization__email, user__username, + user__email, role_description__title, role_description__slug + required: false + schema: + type: string + example: query + - name: o + in: query + description: sort by full_name, username, role_name, grant_key, request_key, + created_at + required: false + schema: + type: string + example: created_at + - name: ot + in: query + description: sort by natural ascending or descending order + required: false + schema: + type: string + example: desc + - name: page + in: query + description: A page number within the paginated result set. + required: false + schema: + type: integer + example: 1 + responses: + "200": + description: "" + content: + application/json: + schema: + required: + - count + - results + type: object + properties: + count: + type: integer + next: + type: string + format: uri + previous: + type: string + format: uri + results: + type: array + items: + $ref: "#/components/schemas/Accessible" + tags: + - users + post: + operationId: users_accessibles_create + description: |- + Creates a request to attach a user to a role on an organization + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + POST /api/users/xia/accessibles/ HTTP/1.1 + + .. code-block:: json + + { + "slug": "cowork" + } + + responds + + .. code-block:: json + + { + "slug": "cowork" + } + requestBody: + $ref: "#/components/requestBodies/Accessible" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Accessible" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: xia + "/users/{user}/accessibles/accept/{verification_key}/": + put: + operationId: users_accessibles_accept_update + description: |- + Accepts a role on an organization. + + **Tags: rbac + + **Examples + + .. code-block:: http + + PUT /api/users/xia/accessibles/accept/0123456789abcef/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "role_description": { + "created_at": "2018-01-01T00:00:00Z", + "title": "Profile Manager", + "slug": "manager", + "is_global": true, + "organization": { + "slug": "cowork", + "full_name": "ABC Corp.", + "printable_name": "ABC Corp.", + "created_at": "2018-01-01T00:00:00Z", + "email": "support@localhost.localdomain" + } + }, + "user": { + "slug": "alice", + "email": "alice@localhost.localdomain", + "full_name": "Alice Doe", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": "1", + "grant_key": null + } + requestBody: + $ref: "#/components/requestBodies/Accessible" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Accessible" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: xia + - name: verification_key + in: path + required: true + schema: + type: string + example: 0123456789abcef + "/users/{user}/accessibles/{role}/": + get: + operationId: users_accessibles_read + description: |- + Lists all relations where a ``User`` has a specified ``Role`` + on an ``Organization``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/users/alice/accessibles/manager HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "slug": "cowork", + "printable_name": "ABC Corp.", + "role_description": "manager", + "request_key": null, + "grant_key": null + } + ] + } + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Accessible" + tags: + - users + post: + operationId: users_accessibles_role_create + description: |- + Lists all relations where a ``User`` has a specified ``Role`` + on an ``Organization``. + + see :doc:`Flexible Security Framework `. + + **Tags: rbac + + **Examples + + .. code-block:: http + + GET /api/users/alice/accessibles/manager HTTP/1.1 + + responds + + .. code-block:: json + + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "created_at": "2018-01-01T00:00:00Z", + "slug": "cowork", + "printable_name": "ABC Corp.", + "role_description": "manager", + "request_key": null, + "grant_key": null + } + ] + } + requestBody: + $ref: "#/components/requestBodies/Accessible" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Accessible" + tags: + - users + parameters: + - name: role + in: path + required: true + schema: + type: string + example: manager + - name: user + in: path + required: true + schema: + type: string + example: xia + "/users/{user}/accessibles/{role}/{organization}/": + post: + operationId: users_accessibles_role_org_create + description: |- + Re-sends the request e-mail that the user is requested a role + on the organization. + + **Tags: rbac + + **Examples + + .. code-block:: http + + POST /api/users/xia/accessibles/manager/cowork/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "created_at": "2018-01-01T00:00:00Z", + "role_description": { + "created_at": "2018-01-01T00:00:00Z", + "title": "Profile Manager", + "slug": "manager", + "is_global": true, + "organization": { + "slug": "cowork", + "full_name": "ABC Corp.", + "printable_name": "ABC Corp.", + "created_at": "2018-01-01T00:00:00Z", + "email": "support@localhost.localdomain" + } + }, + "user": { + "slug": "alice", + "email": "alice@localhost.localdomain", + "full_name": "Alice Doe", + "created_at": "2018-01-01T00:00:00Z" + }, + "request_key": "1", + "grant_key": null + } + requestBody: + $ref: "#/components/requestBodies/RoleAccessible" + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/RoleAccessible" + tags: + - users + delete: + operationId: users_accessibles_delete + description: |- + Dettach a user from one or all roles with regards to an organization, + typically resulting in revoking permissions from this user to manage + part of an organization profile. + + **Tags: rbac + + **Examples + + .. code-block:: http + + DELETE /api/users/xia/accessibles/manager/cowork/ HTTP/1.1 + responses: + "204": + description: "" + tags: + - users + parameters: + - name: organization + in: path + required: true + schema: + type: string + example: cowork + - name: role + in: path + required: true + schema: + type: string + example: manager + - name: user + in: path + required: true + schema: + type: string + example: xia + "/users/{user}/activate/": + post: + operationId: users_activate_create + description: |- + Re-send an activation e-mail if the user is not already activated. + + The template for the e-mail sent to the user can be found in + notification/verification.eml. + + **Tags: auth + + **Example + + .. code-block:: http + + POST /api/users/donny/activate/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "slug": "xia", + "email": "xia@locahost.localdomain", + "full_name": "Xia Lee", + "nick_name": "Xia", + "created_at": "2018-01-01T00:00:00Z", + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/NoModel" + required: true + responses: + "201": + description: success + content: + application/json: + schema: + $ref: "#/components/schemas/Contact" + "400": + description: parameters error + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationError" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: donny + "/users/{user}/api-keys/": + post: + operationId: users_api-keys_create + description: >- + Reset the secret API key with which a user can authenticate + + with the service. + + + **Tags: auth + + + **Example + + + .. code-block:: http + + POST /api/users/donny/api-keys/ HTTP/1.1 + + responds + + + .. code-block:: json + + { + "secret": "tgLwDw5ErQ2pQr5TTdAzSYjvZenHC9pSy7fB3sXWERzynbG5zG6h67pTN4dh7fpy" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/APIKeys" + required: true + responses: + "201": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/APIKeys" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: donny + "/users/{user}/notifications/": + put: + operationId: users_notifications_update + description: |- + Changes notifications preferences for a user. + + **Tags: profile + + **Example + + .. code-block:: http + + POST /api/users/donny/notifications/ HTTP/1.1 + + .. code-block:: json + + { + "notifications": ["user_registered_notice"] + } + + responds + + .. code-block:: json + + { + "notifications": ["user_registered_notice"] + } + requestBody: + $ref: "#/components/requestBodies/Notifications" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Notifications" + tags: + - users + patch: + operationId: users_notifications_partial_update + description: |- + Changes notifications preferences for a user. + + **Tags: profile + + **Example + + .. code-block:: http + + POST /api/users/donny/notifications/ HTTP/1.1 + + .. code-block:: json + + { + "notifications": ["user_registered_notice"] + } + + responds + + .. code-block:: json + + { + "notifications": ["user_registered_notice"] + } + requestBody: + $ref: "#/components/requestBodies/Notifications" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/Notifications" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: donny + "/users/{user}/password/": + put: + operationId: users_password_update + description: |- + Changes the password for a user. + + **Tags: auth + + **Example + + .. code-block:: http + + PUT /api/users/donny/password/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "password": "yeye" + } + requestBody: + $ref: "#/components/requestBodies/PasswordChange" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordChange" + tags: + - users + patch: + operationId: users_password_partial_update + description: |- + Changes the password for a user. + + **Tags: auth + + **Example + + .. code-block:: http + + PUT /api/users/donny/password/ HTTP/1.1 + + responds + + .. code-block:: json + + { + "password": "yeye" + } + requestBody: + $ref: "#/components/requestBodies/PasswordChange" + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordChange" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: donny + "/users/{user}/ssh-keys/": + put: + operationId: users_ssh-keys_update + description: |- + Update public key for a User + + **Tags: auth + + **Example + + .. code-block:: http + + PUT /api/users/donny/ssh-keys/ HTTP/1.1 + + .. code-block:: json + + { + "pubkey": "ssh-rsa AAAAB3N...", + "password": "secret" + } + + responds + + .. code-block:: json + + { + "detail": "ok" + } + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/PublicKey" + required: true + responses: + "200": + description: "" + content: + application/json: + schema: + $ref: "#/components/schemas/PublicKey" + tags: + - users + parameters: + - name: user + in: path + required: true + schema: + type: string + example: donny +servers: + - url: /api +components: + requestBodies: + Plan: + content: + application/json: + schema: + $ref: "#/components/schemas/Plan" + required: true + Card: + content: + application/json: + schema: + $ref: "#/components/schemas/Card" + required: true + EdgeCreate: + content: + application/json: + schema: + $ref: "#/components/schemas/EdgeCreate" + required: true + Notifications: + content: + application/json: + schema: + $ref: "#/components/schemas/Notifications" + required: true + PageElement: + content: + application/json: + schema: + $ref: "#/components/schemas/PageElement" + required: true + Rule: + content: + application/json: + schema: + $ref: "#/components/schemas/Rule" + required: true + Token: + content: + application/json: + schema: + $ref: "#/components/schemas/Token" + required: true + Coupon: + content: + application/json: + schema: + $ref: "#/components/schemas/Coupon" + required: true + BalanceLine: + content: + application/json: + schema: + $ref: "#/components/schemas/BalanceLine" + required: true + OrganizationWithSubscriptions: + content: + application/json: + schema: + $ref: "#/components/schemas/OrganizationWithSubscriptions" + required: true + Subscription: + content: + application/json: + schema: + $ref: "#/components/schemas/Subscription" + required: true + RoleDescriptionCRUD: + content: + application/json: + schema: + $ref: "#/components/schemas/RoleDescriptionCRUD" + required: true + RoleAccessible: + content: + application/json: + schema: + $ref: "#/components/schemas/RoleAccessible" + required: true + App: + content: + application/json: + schema: + $ref: "#/components/schemas/App" + required: true + AppKey: + content: + application/json: + schema: + $ref: "#/components/schemas/AppKey" + required: true + UpdateRule: + content: + application/json: + schema: + $ref: "#/components/schemas/UpdateRule" + required: true + Asset: + content: + application/json: + schema: + $ref: "#/components/schemas/Asset" + "*/*": + schema: + $ref: "#/components/schemas/Asset" + required: true + PageElementTag: + content: + application/json: + schema: + $ref: "#/components/schemas/PageElementTag" + required: true + LessVariable: + content: + application/json: + schema: + $ref: "#/components/schemas/LessVariable" + required: true + SourceCode: + content: + application/json: + schema: + $ref: "#/components/schemas/SourceCode" + required: true + ContactDetail: + content: + application/json: + schema: + $ref: "#/components/schemas/ContactDetail" + required: true + Accessible: + content: + application/json: + schema: + $ref: "#/components/schemas/Accessible" + required: true + PasswordChange: + content: + application/json: + schema: + $ref: "#/components/schemas/PasswordChange" + required: true + securitySchemes: + basic: + type: http + scheme: basic + schemas: + Organization: + required: + - full_name + - email + type: object + properties: + slug: + title: Slug + description: Unique identifier shown in the URL bar + type: string + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + full_name: + title: Full name + description: Full name + type: string + minLength: 1 + email: + title: Email + description: E-mail address + type: string + format: email + minLength: 1 + phone: + title: Phone + description: Phone number + type: string + street_address: + title: Street address + description: Street address + type: string + locality: + title: Locality + description: City/Town + type: string + region: + title: Region + description: State/Province/County + type: string + postal_code: + title: Postal code + description: Zip/Postal code + type: string + country: + title: Country + description: Country + type: string + enum: + - AF + - AX + - AL + - DZ + - AS + - AD + - AO + - AI + - AQ + - AG + - AR + - AM + - AW + - AU + - AT + - AZ + - BS + - BH + - BD + - BB + - BY + - BE + - BZ + - BJ + - BM + - BT + - BO + - BQ + - BA + - BW + - BV + - BR + - IO + - BN + - BG + - BF + - BI + - CV + - KH + - CM + - CA + - KY + - CF + - TD + - CL + - CN + - CX + - CC + - CO + - KM + - CG + - CD + - CK + - CR + - CI + - HR + - CU + - CW + - CY + - CZ + - DK + - DJ + - DM + - DO + - EC + - EG + - SV + - GQ + - ER + - EE + - SZ + - ET + - FK + - FO + - FJ + - FI + - FR + - GF + - PF + - TF + - GA + - GM + - GE + - DE + - GH + - GI + - GR + - GL + - GD + - GP + - GU + - GT + - GG + - GN + - GW + - GY + - HT + - HM + - VA + - HN + - HK + - HU + - IS + - IN + - ID + - IR + - IQ + - IE + - IM + - IL + - IT + - JM + - JP + - JE + - JO + - KZ + - KE + - KI + - KW + - KG + - LA + - LV + - LB + - LS + - LR + - LY + - LI + - LT + - LU + - MO + - MK + - MG + - MW + - MY + - MV + - ML + - MT + - MH + - MQ + - MR + - MU + - YT + - MX + - FM + - MD + - MC + - MN + - ME + - MS + - MA + - MZ + - MM + - NA + - NR + - NP + - NL + - NC + - NZ + - NI + - NE + - NG + - NU + - NF + - KP + - MP + - NO + - OM + - PK + - PW + - PS + - PA + - PG + - PY + - PE + - PH + - PN + - PL + - PT + - PR + - QA + - RE + - RO + - RU + - RW + - BL + - SH + - KN + - LC + - MF + - PM + - VC + - WS + - SM + - ST + - SA + - SN + - RS + - SC + - SL + - SG + - SX + - SK + - SI + - SB + - SO + - ZA + - GS + - KR + - SS + - ES + - LK + - SD + - SR + - SJ + - SE + - CH + - SY + - TW + - TJ + - TZ + - TH + - TL + - TG + - TK + - TO + - TT + - TN + - TR + - TM + - TC + - TV + - UG + - UA + - AE + - GB + - UM + - US + - UY + - UZ + - VU + - VE + - VN + - VG + - VI + - WF + - EH + - YE + - ZM + - ZW + default_timezone: + title: Default timezone + description: Timezone to use when reporting metrics + type: string + minLength: 1 + printable_name: + title: Printable name + type: string + readOnly: true + minLength: 1 + is_provider: + title: Is provider + description: The organization can fulfill the provider side of a subscription. + type: boolean + is_bulk_buyer: + title: Is bulk buyer + description: Enable GroupBuy (what is it?) + type: boolean + type: + title: Type + description: One of 'organization', 'personal' or 'user' + type: string + readOnly: true + credentials: + title: Credentials + type: string + readOnly: true + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + User: + required: + - slug + type: object + properties: + slug: + title: Slug + description: Effectively the username. The variable is named `slug` such that + front-end code can be re-used between Organization and User records. + type: string + pattern: ^[\w.@+-]+$ + minLength: 1 + email: + title: Email + description: E-mail address for the user + type: string + format: email + readOnly: true + minLength: 1 + full_name: + title: Full name + description: Full name for the contact (effectively first name followed by last + name) + type: string + readOnly: true + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + Credentials: + required: + - username + - password + type: object + properties: + username: + title: Username + description: Username to identify the account + type: string + pattern: ^[\w.@+-]+$ + minLength: 1 + password: + title: Password + description: Secret password for the account + type: string + minLength: 1 + code: + title: Code + description: One-time code. This field will be checked against an expected code + when multi-factor authentication (MFA) is enabled. + type: integer + Token: + required: + - token + type: object + properties: + token: + title: Token + description: Token used to authenticate user on every HTTP request + type: string + minLength: 1 + ValidationError: + required: + - detail + type: object + properties: + detail: + title: Detail + description: Describes the reason for the error in plain text + type: string + minLength: 1 + PasswordReset: + required: + - email + type: object + properties: + email: + title: Email + description: Primary e-mail to contact user + type: string + format: email + minLength: 1 + Register: + required: + - email + - full_name + type: object + properties: + username: + title: Username + description: Username to identify the account + type: string + minLength: 1 + password: + title: Password + description: Password with which a user can authenticate with the service + type: string + minLength: 1 + email: + title: Email + description: Primary e-mail to contact user + type: string + format: email + minLength: 1 + full_name: + title: Full name + description: Full name (effectively first name followed by last name) + type: string + minLength: 1 + organization_name: + title: Organization name + description: Organization name that owns the billing, registered with the user as + profile manager + type: string + minLength: 1 + street_address: + title: Street address + description: Street address for the billing profile + type: string + minLength: 1 + locality: + title: Locality + description: City/Town for the billing profile + type: string + minLength: 1 + region: + title: Region + description: State/Province/County for the billing profile + type: string + minLength: 1 + postal_code: + title: Postal code + description: Zip/Postal Code for the billing profile + type: string + minLength: 1 + country: + title: Country + description: Country for the billing profile + type: string + minLength: 1 + phone: + title: Phone + description: Phone number for the billing profile + type: string + minLength: 1 + CreateUser: + required: + - email + - full_name + type: object + properties: + username: + title: Username + description: Username to identify the account + type: string + minLength: 1 + password: + title: Password + description: Password with which a user can authenticate with the service + type: string + minLength: 1 + email: + title: Email + description: Primary e-mail to contact user + type: string + format: email + minLength: 1 + full_name: + title: Full name + description: Full name (effectively first name followed by last name) + type: string + minLength: 1 + AuthRealms: + required: + - location + - access_key + - acl + - policy + - signature + - security_token + - x_amz_credential + - x_amz_date + type: object + properties: + location: + title: Location + description: URL to upload files + type: string + minLength: 1 + access_key: + title: Access key + description: Access key + type: string + minLength: 1 + acl: + title: Acl + description: ACL (i.e. private or public-read) + type: string + minLength: 1 + policy: + title: Policy + description: Policy + type: string + minLength: 1 + signature: + title: Signature + description: Signature + type: string + minLength: 1 + security_token: + title: Security token + description: Security token + type: string + minLength: 1 + x_amz_credential: + title: X amz credential + description: AMZ Credential + type: string + minLength: 1 + x_amz_date: + title: X amz date + description: AMZ Date + type: string + minLength: 1 + Charge: + required: + - created_at + - last4 + - exp_date + - processor_key + - state + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + amount: + title: Amount + description: Total amount in currency unit + type: integer + unit: + title: Unit + description: "Three-letter ISO 4217 code for currency unit (ex: usd)" + type: string + maxLength: 3 + minLength: 1 + readable_amount: + title: Readable amount + description: Amount and unit in a commonly accepted readable format + type: string + readOnly: true + description: + title: Description + description: Description for the charge as appears on billing statements + type: string + minLength: 1 + last4: + title: Last4 + description: Last 4 digits of the credit card used + type: integer + exp_date: + title: Exp date + description: Expiration date of the credit card used + type: string + format: date + processor_key: + title: Processor key + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + maxLength: 50 + minLength: 1 + state: + title: State + description: Current state (i.e. created, done, failed, disputed) + type: string + minLength: 1 + EmailChargeReceipt: + type: object + properties: + charge_id: + title: Charge id + description: Charge identifier (i.e. matches the URL {charge} parameter) + type: string + readOnly: true + minLength: 1 + email: + title: Email + description: E-mail address to which the receipt was sent. + type: string + format: email + readOnly: true + minLength: 1 + RefundChargeItem: + required: + - num + type: object + properties: + num: + title: Num + description: Line item index counting from zero. + type: integer + refunded_amount: + title: Refunded amount + description: The amount to refund cannot be higher than the amount of the line + item minus the total amount already refunded on that line item. + type: integer + RefundCharge: + required: + - lines + type: object + properties: + lines: + type: array + items: + $ref: "#/components/schemas/RefundChargeItem" + Transaction: + required: + - created_at + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + description: + title: Description + description: Free-form text description for the transaction + type: string + readOnly: true + minLength: 1 + amount: + title: Amount + description: Amount being transfered + type: string + readOnly: true + minLength: 1 + is_debit: + title: Is debit + description: True if the transaction is indentified as a debit in the API context + type: string + readOnly: true + minLength: 1 + orig_account: + title: Orig account + description: Source account from which funds are withdrawn + type: string + maxLength: 255 + minLength: 1 + orig_organization: + title: Orig organization + description: Source organization from which funds are withdrawn + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + orig_amount: + title: Orig amount + description: Amount withdrawn from source in orig_unit + type: integer + orig_unit: + title: Orig unit + description: "Three-letter ISO 4217 code for source currency unit (ex: usd)" + type: string + maxLength: 3 + minLength: 1 + dest_account: + title: Dest account + description: Target account to which funds are deposited + type: string + maxLength: 255 + minLength: 1 + dest_organization: + title: Dest organization + description: Target organization to which funds are deposited + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + dest_amount: + title: Dest amount + description: Amount deposited into target in dest_unit + type: integer + dest_unit: + title: Dest unit + description: "Three-letter ISO 4217 code for target currency unit (ex: usd)" + type: string + maxLength: 3 + minLength: 1 + Bank: + required: + - bank_name + - last4 + - balance_amount + - balance_unit + type: object + properties: + bank_name: + title: Bank name + description: Name of the deposit account + type: string + minLength: 1 + last4: + title: Last4 + description: Last 4 characters of the deposit account identifier + type: string + minLength: 1 + balance_amount: + title: Balance amount + description: Amount available to transfer to the provider deposit account + type: integer + balance_unit: + title: Balance unit + description: "Three-letter ISO 4217 code for currency unit (ex: usd)" + type: string + minLength: 1 + Card: + required: + - last4 + - exp_date + type: object + properties: + last4: + title: Last4 + description: Last 4 digits of the credit card on file + type: string + minLength: 1 + exp_date: + title: Exp date + description: Expiration date of the credit card on file + type: string + minLength: 1 + Plan: + title: Plan + type: object + properties: + slug: + title: Slug + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + minLength: 1 + title: + title: Title + description: Title for the plan + type: string + minLength: 1 + description: + title: Description + description: Free-form text description for the plan + type: string + minLength: 1 + is_active: + title: Is active + description: True when customers can subscribe to the plan + type: boolean + setup_amount: + title: Setup amount + description: One-time amount to pay when the subscription starts + type: integer + period_amount: + title: Period amount + description: Amount billed every period + type: integer + interval: + title: Interval + description: Natural period for the subscription + type: string + app_url: + title: App url + type: string + readOnly: true + advance_discount: + title: Advance discount + description: Incremental discount for payment of multiple periods (in %%). + type: integer + maximum: 10000 + unit: + title: Unit + type: string + maxLength: 3 + minLength: 1 + organization: + title: Organization + description: Provider of the plan + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + period_length: + title: Period length + description: Natural period length of a subscription to the plan (monthly, + yearly, etc.) + type: integer + renewal_type: + title: Renewal type + description: Natural period for the subscription + type: string + is_not_priced: + title: Is not priced + type: boolean + created_at: + title: Created at + type: string + format: date-time + readOnly: true + skip_optin_on_grant: + title: Skip optin on grant + description: True when a subscriber can automatically be subscribed to the plan + by its provider. Otherwise the subscriber must manually accept the + subscription. (defaults to False) + type: boolean + optin_on_request: + title: Optin on request + description: True when a provider must manually accept a subscription to the plan + initiated by a subscriber. (defaults to False) + type: boolean + readOnly: true + Subscription: + title: Subscription + description: Subscription lines and options refer to. + required: + - ends_at + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + ends_at: + title: Ends at + description: Date/time when the subscription period currently ends (in ISO format) + type: string + format: date-time + description: + title: Description + description: Free-form text description for the subscription + type: string + organization: + $ref: "#/components/schemas/Organization" + plan: + $ref: "#/components/schemas/Plan" + auto_renew: + title: Auto renew + description: The subscription is set to auto-renew at the end of the period + type: boolean + editable: + title: Editable + description: True if the request user is able to update the subscription. + Typically a manager for the plan provider. + type: string + readOnly: true + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + grant_key: + title: Grant key + type: string + readOnly: true + minLength: 1 + request_key: + title: Request key + type: string + readOnly: true + minLength: 1 + readOnly: true + Invoicable: + required: + - lines + type: object + properties: + subscription: + $ref: "#/components/schemas/Subscription" + lines: + description: Line items to charge on checkout. + type: array + items: + $ref: "#/components/schemas/Transaction" + options: + description: Options to replace line items. + type: array + items: + $ref: "#/components/schemas/Transaction" + readOnly: true + OrganizationCart: + required: + - items + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/Invoicable" + CheckoutItem: + required: + - option + type: object + properties: + option: + title: Option + description: selected plan option during checkout + type: integer + Checkout: + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/CheckoutItem" + remember_card: + title: Remember card + description: attaches the payment card to the Organization when true + type: boolean + processor_token: + title: Processor token + description: one-time token generated by the processorfrom the payment card. + type: string + maxLength: 255 + minLength: 1 + street_address: + title: Street address + description: Street address + type: string + locality: + title: Locality + description: City/Town + type: string + region: + title: Region + description: State/Province/County + type: string + postal_code: + title: Postal code + description: Zip/Postal code + type: string + country: + title: Country + description: Country + type: string + Coupon: + required: + - code + type: object + properties: + code: + title: Code + description: Unique identifier per provider, typically used in URLs + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + maxLength: 50 + minLength: 1 + percent: + title: Percent + description: Percentage discounted + type: integer + maximum: 100 + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + ends_at: + title: Ends at + description: Date/time at which the coupon code expires (in ISO format) + type: string + format: date-time + description: + title: Description + description: Free-form text description for the coupon + type: string + OfflineTransaction: + required: + - subscription + - created_at + - amount + type: object + properties: + subscription: + title: Subscription + description: The subscription the offline transaction refers to. + type: string + minLength: 1 + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + amount: + title: Amount + type: string + format: decimal + descr: + title: Descr + description: Free-form text description for the transaction + type: string + minLength: 1 + CartItemCreate: + required: + - plan + type: object + properties: + plan: + title: Plan + description: The plan to add into the request.user cart. + type: string + option: + title: Option + type: integer + full_name: + title: Full name + description: Full name of the person that will benefit from the subscription + (GroupBuy) + type: string + maxLength: 150 + sync_on: + title: Sync on + type: string + maxLength: 255 + email: + title: Email + type: string + maxLength: 255 + RedeemCoupon: + required: + - code + type: object + properties: + code: + title: Code + description: Coupon code to redeem + type: string + minLength: 1 + CartItemUpload: + required: + - created + - updated + - failed + type: object + properties: + created: + title: Created + type: string + minLength: 1 + updated: + title: Updated + type: string + minLength: 1 + failed: + title: Failed + type: string + minLength: 1 + Activity: + required: + - account + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + created_by: + title: Created by + description: User that created the activity + type: string + pattern: ^[\w.@+-]+$ + readOnly: true + text: + title: Text + description: Free form text description of the activity + type: string + account: + title: Account + description: Account the activity is associated to + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + AgreementSign: + required: + - read_terms + type: object + properties: + read_terms: + title: Read terms + description: I have read and understand these terms and conditions + type: boolean + last_signed: + title: Last signed + type: string + format: date-time + readOnly: true + Table: + required: + - key + - selector + - values + type: object + properties: + key: + title: Key + description: Unique key in the table for the data series + type: string + minLength: 1 + selector: + title: Selector + description: Filter on the Transaction accounts + type: string + minLength: 1 + values: + title: Values + description: Datapoints in the serie + type: string + minLength: 1 + Metrics: + required: + - scale + - unit + - title + - table + type: object + properties: + scale: + title: Scale + description: "The scale of the number reported in the tables (ex: 1000 when + numbers are reported in thousands of dollars)" + type: number + unit: + title: Unit + description: "Three-letter ISO 4217 code for currency unit (ex: usd)" + type: string + minLength: 1 + title: + title: Title + description: Title for the table + type: string + minLength: 1 + table: + type: array + items: + $ref: "#/components/schemas/Table" + BalanceLine: + required: + - title + - rank + type: object + properties: + title: + title: Title + description: Title for the row + type: string + maxLength: 255 + minLength: 1 + selector: + title: Selector + description: Filter on the Transaction accounts + type: string + maxLength: 255 + rank: + title: Rank + description: Absolute position of the row in the list of rows for the table + type: integer + CartItem: + required: + - plan + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + user: + $ref: "#/components/schemas/User" + plan: + title: Plan + type: string + option: + title: Option + type: integer + full_name: + title: Full name + description: Full name of the person that will benefit from the subscription + (GroupBuy) + type: string + maxLength: 150 + sync_on: + title: Sync on + type: string + maxLength: 255 + OrganizationCreate: + required: + - full_name + - email + - type + type: object + properties: + slug: + title: Slug + description: Unique identifier shown in the URL bar + type: string + full_name: + title: Full name + description: Full name + type: string + minLength: 1 + default_timezone: + title: Default timezone + description: Timezone to use when reporting metrics + type: string + minLength: 1 + email: + title: Email + description: E-mail address + type: string + format: email + minLength: 1 + phone: + title: Phone + description: Phone number + type: string + street_address: + title: Street address + description: Street address + type: string + locality: + title: Locality + description: City/Town + type: string + region: + title: Region + description: State/Province/County + type: string + postal_code: + title: Postal code + description: Zip/Postal code + type: string + country: + title: Country + description: Country + type: string + enum: + - AF + - AX + - AL + - DZ + - AS + - AD + - AO + - AI + - AQ + - AG + - AR + - AM + - AW + - AU + - AT + - AZ + - BS + - BH + - BD + - BB + - BY + - BE + - BZ + - BJ + - BM + - BT + - BO + - BQ + - BA + - BW + - BV + - BR + - IO + - BN + - BG + - BF + - BI + - CV + - KH + - CM + - CA + - KY + - CF + - TD + - CL + - CN + - CX + - CC + - CO + - KM + - CG + - CD + - CK + - CR + - CI + - HR + - CU + - CW + - CY + - CZ + - DK + - DJ + - DM + - DO + - EC + - EG + - SV + - GQ + - ER + - EE + - SZ + - ET + - FK + - FO + - FJ + - FI + - FR + - GF + - PF + - TF + - GA + - GM + - GE + - DE + - GH + - GI + - GR + - GL + - GD + - GP + - GU + - GT + - GG + - GN + - GW + - GY + - HT + - HM + - VA + - HN + - HK + - HU + - IS + - IN + - ID + - IR + - IQ + - IE + - IM + - IL + - IT + - JM + - JP + - JE + - JO + - KZ + - KE + - KI + - KW + - KG + - LA + - LV + - LB + - LS + - LR + - LY + - LI + - LT + - LU + - MO + - MK + - MG + - MW + - MY + - MV + - ML + - MT + - MH + - MQ + - MR + - MU + - YT + - MX + - FM + - MD + - MC + - MN + - ME + - MS + - MA + - MZ + - MM + - NA + - NR + - NP + - NL + - NC + - NZ + - NI + - NE + - NG + - NU + - NF + - KP + - MP + - NO + - OM + - PK + - PW + - PS + - PA + - PG + - PY + - PE + - PH + - PN + - PL + - PT + - PR + - QA + - RE + - RO + - RU + - RW + - BL + - SH + - KN + - LC + - MF + - PM + - VC + - WS + - SM + - ST + - SA + - SN + - RS + - SC + - SL + - SG + - SX + - SK + - SI + - SB + - SO + - ZA + - GS + - KR + - SS + - ES + - LK + - SD + - SR + - SJ + - SE + - CH + - SY + - TW + - TJ + - TZ + - TH + - TL + - TG + - TK + - TO + - TT + - TN + - TR + - TM + - TC + - TV + - UG + - UA + - AE + - GB + - UM + - US + - UY + - UZ + - VU + - VE + - VN + - VG + - VI + - WF + - EH + - YE + - ZM + - ZW + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + type: + title: Type + description: One of 'organization', 'personal' or 'user' + type: string + minLength: 1 + WithSubscription: + required: + - ends_at + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + ends_at: + title: Ends at + description: Date/time when the subscription period currently ends (in ISO format) + type: string + format: date-time + plan: + title: Plan + type: string + readOnly: true + auto_renew: + title: Auto renew + description: The subscription is set to auto-renew at the end of the period + type: boolean + Profile: + required: + - full_name + - email + type: object + properties: + slug: + title: Slug + description: Unique identifier shown in the URL bar + type: string + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + full_name: + title: Full name + description: Full name + type: string + minLength: 1 + email: + title: Email + description: E-mail address + type: string + format: email + minLength: 1 + phone: + title: Phone + description: Phone number + type: string + street_address: + title: Street address + description: Street address + type: string + locality: + title: Locality + description: City/Town + type: string + region: + title: Region + description: State/Province/County + type: string + postal_code: + title: Postal code + description: Zip/Postal code + type: string + country: + title: Country + description: Country + type: string + enum: + - AF + - AX + - AL + - DZ + - AS + - AD + - AO + - AI + - AQ + - AG + - AR + - AM + - AW + - AU + - AT + - AZ + - BS + - BH + - BD + - BB + - BY + - BE + - BZ + - BJ + - BM + - BT + - BO + - BQ + - BA + - BW + - BV + - BR + - IO + - BN + - BG + - BF + - BI + - CV + - KH + - CM + - CA + - KY + - CF + - TD + - CL + - CN + - CX + - CC + - CO + - KM + - CG + - CD + - CK + - CR + - CI + - HR + - CU + - CW + - CY + - CZ + - DK + - DJ + - DM + - DO + - EC + - EG + - SV + - GQ + - ER + - EE + - SZ + - ET + - FK + - FO + - FJ + - FI + - FR + - GF + - PF + - TF + - GA + - GM + - GE + - DE + - GH + - GI + - GR + - GL + - GD + - GP + - GU + - GT + - GG + - GN + - GW + - GY + - HT + - HM + - VA + - HN + - HK + - HU + - IS + - IN + - ID + - IR + - IQ + - IE + - IM + - IL + - IT + - JM + - JP + - JE + - JO + - KZ + - KE + - KI + - KW + - KG + - LA + - LV + - LB + - LS + - LR + - LY + - LI + - LT + - LU + - MO + - MK + - MG + - MW + - MY + - MV + - ML + - MT + - MH + - MQ + - MR + - MU + - YT + - MX + - FM + - MD + - MC + - MN + - ME + - MS + - MA + - MZ + - MM + - NA + - NR + - NP + - NL + - NC + - NZ + - NI + - NE + - NG + - NU + - NF + - KP + - MP + - NO + - OM + - PK + - PW + - PS + - PA + - PG + - PY + - PE + - PH + - PN + - PL + - PT + - PR + - QA + - RE + - RO + - RU + - RW + - BL + - SH + - KN + - LC + - MF + - PM + - VC + - WS + - SM + - ST + - SA + - SN + - RS + - SC + - SL + - SG + - SX + - SK + - SI + - SB + - SO + - ZA + - GS + - KR + - SS + - ES + - LK + - SD + - SR + - SJ + - SE + - CH + - SY + - TW + - TJ + - TZ + - TH + - TL + - TG + - TK + - TO + - TT + - TN + - TR + - TM + - TC + - TV + - UG + - UA + - AE + - GB + - UM + - US + - UY + - UZ + - VU + - VE + - VN + - VG + - VI + - WF + - EH + - YE + - ZM + - ZW + default_timezone: + title: Default timezone + description: Timezone to use when reporting metrics + type: string + minLength: 1 + printable_name: + title: Printable name + type: string + readOnly: true + minLength: 1 + is_provider: + title: Is provider + description: The organization can fulfill the provider side of a subscription. + type: boolean + is_bulk_buyer: + title: Is bulk buyer + description: Enable GroupBuy (what is it?) + type: boolean + type: + title: Type + description: One of 'organization', 'personal' or 'user' + type: string + readOnly: true + credentials: + title: Credentials + type: string + readOnly: true + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + activities: + type: array + items: + $ref: "#/components/schemas/Activity" + readOnly: true + subscriptions: + type: array + items: + $ref: "#/components/schemas/WithSubscription" + readOnly: true + OrganizationWithSubscriptions: + required: + - full_name + - email + type: object + properties: + slug: + title: Slug + description: Unique identifier shown in the URL bar + type: string + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + full_name: + title: Full name + description: Full name + type: string + minLength: 1 + email: + title: Email + description: E-mail address + type: string + format: email + minLength: 1 + phone: + title: Phone + description: Phone number + type: string + street_address: + title: Street address + description: Street address + type: string + locality: + title: Locality + description: City/Town + type: string + region: + title: Region + description: State/Province/County + type: string + postal_code: + title: Postal code + description: Zip/Postal code + type: string + country: + title: Country + description: Country + type: string + enum: + - AF + - AX + - AL + - DZ + - AS + - AD + - AO + - AI + - AQ + - AG + - AR + - AM + - AW + - AU + - AT + - AZ + - BS + - BH + - BD + - BB + - BY + - BE + - BZ + - BJ + - BM + - BT + - BO + - BQ + - BA + - BW + - BV + - BR + - IO + - BN + - BG + - BF + - BI + - CV + - KH + - CM + - CA + - KY + - CF + - TD + - CL + - CN + - CX + - CC + - CO + - KM + - CG + - CD + - CK + - CR + - CI + - HR + - CU + - CW + - CY + - CZ + - DK + - DJ + - DM + - DO + - EC + - EG + - SV + - GQ + - ER + - EE + - SZ + - ET + - FK + - FO + - FJ + - FI + - FR + - GF + - PF + - TF + - GA + - GM + - GE + - DE + - GH + - GI + - GR + - GL + - GD + - GP + - GU + - GT + - GG + - GN + - GW + - GY + - HT + - HM + - VA + - HN + - HK + - HU + - IS + - IN + - ID + - IR + - IQ + - IE + - IM + - IL + - IT + - JM + - JP + - JE + - JO + - KZ + - KE + - KI + - KW + - KG + - LA + - LV + - LB + - LS + - LR + - LY + - LI + - LT + - LU + - MO + - MK + - MG + - MW + - MY + - MV + - ML + - MT + - MH + - MQ + - MR + - MU + - YT + - MX + - FM + - MD + - MC + - MN + - ME + - MS + - MA + - MZ + - MM + - NA + - NR + - NP + - NL + - NC + - NZ + - NI + - NE + - NG + - NU + - NF + - KP + - MP + - NO + - OM + - PK + - PW + - PS + - PA + - PG + - PY + - PE + - PH + - PN + - PL + - PT + - PR + - QA + - RE + - RO + - RU + - RW + - BL + - SH + - KN + - LC + - MF + - PM + - VC + - WS + - SM + - ST + - SA + - SN + - RS + - SC + - SL + - SG + - SX + - SK + - SI + - SB + - SO + - ZA + - GS + - KR + - SS + - ES + - LK + - SD + - SR + - SJ + - SE + - CH + - SY + - TW + - TJ + - TZ + - TH + - TL + - TG + - TK + - TO + - TT + - TN + - TR + - TM + - TC + - TV + - UG + - UA + - AE + - GB + - UM + - US + - UY + - UZ + - VU + - VE + - VN + - VG + - VI + - WF + - EH + - YE + - ZM + - ZW + default_timezone: + title: Default timezone + description: Timezone to use when reporting metrics + type: string + minLength: 1 + printable_name: + title: Printable name + type: string + readOnly: true + minLength: 1 + is_provider: + title: Is provider + description: The organization can fulfill the provider side of a subscription. + type: boolean + is_bulk_buyer: + title: Is bulk buyer + description: Enable GroupBuy (what is it?) + type: boolean + type: + title: Type + description: One of 'organization', 'personal' or 'user' + type: string + readOnly: true + picture: + title: Profile picture + description: Profile picture + type: string + format: uri + maxLength: 2083 + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + subscriptions: + type: array + items: + $ref: "#/components/schemas/WithSubscription" + readOnly: true + SubscriptionCreate: + required: + - organization + type: object + properties: + organization: + $ref: "#/components/schemas/OrganizationCreate" + message: + title: Message + type: string + minLength: 1 + Role: + type: object + properties: + created_at: + title: Created at + type: string + format: date-time + readOnly: true + user: + $ref: "#/components/schemas/User" + request_key: + title: Request key + type: string + readOnly: true + minLength: 1 + grant_key: + title: Grant key + type: string + readOnly: true + minLength: 1 + organization: + $ref: "#/components/schemas/Organization" + role_description: + title: Role description + type: string + readOnly: true + accept_request_api_url: + title: Accept request api url + type: string + readOnly: true + remove_api_url: + title: Remove api url + type: string + readOnly: true + RoleDescriptionCRUD: + required: + - title + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + title: + title: Title + description: Short description of the role. Grammatical rules to pluralize the + title might be used in User Interfaces. + type: string + maxLength: 20 + minLength: 1 + slug: + title: Slug + description: Unique identifier shown in the URL bar + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + minLength: 1 + is_global: + title: Is global + type: string + readOnly: true + roles: + title: Roles + type: string + readOnly: true + UserRoleCreate: + required: + - slug + type: object + properties: + slug: + title: Slug + type: string + pattern: "[a-zA-Z0-9_\\-\\+\\.]+" + minLength: 1 + email: + title: Email + type: string + format: email + maxLength: 254 + minLength: 1 + message: + title: Message + type: string + maxLength: 255 + minLength: 1 + RoleDescription: + title: Role description + required: + - title + - slug + type: object + properties: + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + title: + title: Title + description: Short description of the role. Grammatical rules to pluralize the + title might be used in User Interfaces. + type: string + maxLength: 20 + minLength: 1 + slug: + title: Slug + description: Unique identifier shown in the URL bar + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + maxLength: 50 + minLength: 1 + is_global: + title: Is global + type: string + readOnly: true + organization: + $ref: "#/components/schemas/Organization" + readOnly: true + RoleAccessible: + type: object + properties: + created_at: + title: Created at + type: string + format: date-time + readOnly: true + request_key: + title: Request key + type: string + maxLength: 40 + grant_key: + title: Grant key + type: string + maxLength: 40 + role_description: + $ref: "#/components/schemas/RoleDescription" + user: + $ref: "#/components/schemas/User" + App: + type: object + properties: + slug: + title: Slug + description: unique identifier for the site (also serves as subdomain) + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + minLength: 1 + entry_point: + title: Entry point + description: Entry point to which requests will be redirected to + type: string + format: uri + maxLength: 100 + minLength: 1 + session_backend: + title: Session backend + description: Format to encode session in the forwarded HTTP request + type: integer + enum: + - 0 + - 1 + - 2 + authentication: + title: Authentication + description: Restricted authentication and registration + type: string + welcome_email: + title: Welcome email + description: Send a welcome e-mail to newly registered users + type: boolean + show_edit_tools: + title: Show edit tools + type: boolean + Engagement: + required: + - slug + - count + type: object + properties: + slug: + title: Slug + type: string + minLength: 1 + count: + title: Count + type: integer + Engagements: + required: + - engagements + - active_users + type: object + properties: + engagements: + type: array + items: + $ref: "#/components/schemas/Engagement" + active_users: + title: Active users + type: integer + UserEngagement: + required: + - username + type: object + properties: + username: + title: Username + description: Required. 150 characters or fewer. Letters, digits and @/./+/-/_ + only. + type: string + pattern: ^[\w.@+-]+$ + maxLength: 150 + minLength: 1 + engagements: + title: Engagements + type: string + readOnly: true + AppKey: + type: object + properties: + enc_key: + title: Enc key + description: Key used to decrypt the encoded session information. + type: string + readOnly: true + minLength: 1 + Rule: + required: + - rank + - path + type: object + properties: + rank: + title: Rank + description: Determines the order in which rules are considered + type: integer + path: + title: Path + description: OpenAPI path against which requests are matched + type: string + maxLength: 255 + minLength: 1 + allow: + title: Allow + description: Method applied to grant or deny access + type: string + minLength: 1 + is_forward: + title: Is forward + description: When access is granted, should the request be forwarded + type: boolean + engaged: + title: Engaged + description: Tags to check if it is the first time a user engages + type: string + UpdateRule: + required: + - rank + type: object + properties: + rank: + title: Rank + description: Determines the order in which rules are considered + type: integer + path: + title: Path + description: OpenAPI path against which requests are matched + type: string + readOnly: true + minLength: 1 + allow: + title: Allow + description: Method applied to grant or deny access + type: string + minLength: 1 + is_forward: + title: Is forward + description: When access is granted, should the request be forwarded + type: boolean + engaged: + title: Engaged + description: Tags to check if it is the first time a user engages + type: string + SessionData: + required: + - forward_session + - forward_session_header + - forward_url + type: object + properties: + forward_session: + title: Forward session + description: The session being forwarded + type: string + minLength: 1 + forward_session_header: + title: Forward session header + description: The HTTP header that encodes the session + type: string + minLength: 1 + forward_url: + title: Forward url + description: The URL end point where the request is forwarded + type: string + minLength: 1 + ThemePackageUploadBody: + required: + - files + type: object + properties: + files: + title: Files + description: Content of the theme package as a zip file. + type: string + minLength: 1 + ThemePackageUpload: + type: object + properties: + location: + title: Location + description: URL where the theme package was uploaded. + type: string + readOnly: true + minLength: 1 + Asset: + required: + - location + type: object + properties: + location: + title: Location + description: URL where the asset content is stored. + type: string + minLength: 1 + updated_at: + title: Updated at + description: Last date/time the asset content was updated. + type: string + format: date-time + tags: + title: Tags + description: Tags associated to the asset. + type: string + minLength: 1 + PageElement: + type: object + properties: + slug: + title: Slug + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + minLength: 1 + path: + title: Path + type: string + readOnly: true + title: + title: Title + type: string + maxLength: 300 + text: + title: Text + type: string + minLength: 1 + tag: + title: Tag + type: string + minLength: 1 + orig_elements: + type: array + items: + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + minLength: 1 + dest_elements: + type: array + items: + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + minLength: 1 + EdgeCreate: + required: + - source + type: object + properties: + source: + title: Source + type: string + minLength: 1 + rank: + title: Rank + type: integer + external_key: + title: External key + type: string + minLength: 1 + RelationShip: + type: object + properties: + orig_elements: + type: array + items: + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + minLength: 1 + dest_elements: + type: array + items: + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + minLength: 1 + PageElementTag: + type: object + properties: + tag: + title: Tag + type: string + maxLength: 255 + LessVariable: + required: + - name + - value + type: object + properties: + name: + title: Name + type: string + maxLength: 250 + minLength: 1 + value: + title: Value + type: string + maxLength: 250 + minLength: 1 + created_at: + title: Created at + type: string + format: date-time + readOnly: true + updated_at: + title: Updated at + type: string + format: date-time + readOnly: true + SourceCode: + type: object + properties: + path: + title: Path + type: string + maxLength: 255 + minLength: 1 + text: + title: Text + type: string + maxLength: 100000 + minLength: 1 + Contact: + required: + - email + type: object + properties: + slug: + title: Slug + description: Unique identifier shown in the URL bar, effectively the username for + profiles with login credentials. + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + minLength: 1 + printable_name: + title: Printable name + type: string + readOnly: true + picture: + title: URL to a profile picture + description: Profile picture + type: string + format: uri + maxLength: 2083 + email: + title: E-mail address + description: E-mail address + type: string + format: email + maxLength: 254 + minLength: 1 + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + credentials: + title: Credentials + description: True if the user has valid login credentials + type: string + readOnly: true + ContactDetail: + required: + - email + type: object + properties: + slug: + title: Slug + description: Unique identifier shown in the URL bar, effectively the username for + profiles with login credentials. + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + readOnly: true + minLength: 1 + printable_name: + title: Printable name + type: string + readOnly: true + picture: + title: URL to a profile picture + description: Profile picture + type: string + format: uri + maxLength: 2083 + email: + title: E-mail address + description: E-mail address + type: string + format: email + maxLength: 254 + minLength: 1 + created_at: + title: Created at + description: Date/time of creation (in ISO format) + type: string + format: date-time + readOnly: true + credentials: + title: Credentials + description: True if the user has valid login credentials + type: string + readOnly: true + full_name: + title: Full name + description: Full name (effectively first name followed by last name) + type: string + maxLength: 60 + nick_name: + title: Nick name + description: Short casual name used to address the contact + type: string + maxLength: 60 + extra: + title: Extra + description: Extra meta data (can be stringify JSON) + type: string + minLength: 1 + activities: + type: array + items: + $ref: "#/components/schemas/Activity" + readOnly: true + Accessible: + required: + - slug + - printable_name + - email + type: object + properties: + created_at: + title: Created at + type: string + format: date-time + readOnly: true + request_key: + title: Request key + type: string + readOnly: true + minLength: 1 + slug: + title: Slug + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + minLength: 1 + printable_name: + title: Printable name + type: string + minLength: 1 + email: + title: Email + type: string + minLength: 1 + role_description: + $ref: "#/components/schemas/RoleDescription" + home_url: + title: Home url + type: string + readOnly: true + settings_url: + title: Settings url + type: string + readOnly: true + accept_grant_api_url: + title: Accept grant api url + type: string + readOnly: true + remove_api_url: + title: Remove api url + type: string + readOnly: true + NoModel: + type: object + properties: {} + APIKeys: + required: + - password + type: object + properties: + secret: + title: Secret + description: Secret API Key used to authenticate user on every HTTP request + type: string + readOnly: true + maxLength: 128 + minLength: 1 + password: + title: Password + description: Password of the user making the HTTP request + type: string + maxLength: 128 + minLength: 1 + Notifications: + required: + - notifications + type: object + properties: + notifications: + type: array + items: + type: string + format: slug + pattern: ^[-a-zA-Z0-9_]+$ + uniqueItems: true + PasswordChange: + required: + - password + - new_password + type: object + properties: + password: + title: Password + description: Password of the user making the HTTP request + type: string + minLength: 1 + new_password: + title: New password + description: New password for the user referenced in the URL + type: string + minLength: 1 + PublicKey: + required: + - password + - pubkey + type: object + properties: + password: + title: Password + description: Password of the user making the HTTP request + type: string + minLength: 1 + pubkey: + title: Pubkey + description: New public key for the user referenced in the URL + type: string + maxLength: 500 + minLength: 1 diff --git a/package.json b/package.json index 32549b621..b36defd5a 100644 --- a/package.json +++ b/package.json @@ -35,7 +35,8 @@ "vue": "^2.5.17", "vue2-filters": "^0.3.0", "uiv": "^0.31.5", - "vue-croppa": "^1.3.8" + "vue-croppa": "^1.3.8", + "swagger-cli": "^2.2.2" }, "resolutions": { "jquery": "1.11.1"