This project aims to allow making an API request using any of our supported OpenAPI SDKs.
See ./demo for a demo on how this project may be used in our testing suite.
Each SDK will have its own container image. You can build all containers in one go by running:
./build allor build each individually by passing the SDK as parameter:
# dotnet
./build dotnet
# java
./build java
# Node
./build node
# PHP
./build php
# Python
./build python
# Ruby
./build rubyYou run any container using the ./run script and passing the SDK as parameter:
$ ./run php
Uses the selected Dropbox Sign SDK to make a request to the Dropbox Sign API
--sdk one of "dotnet", "java", "node", "php", "python", "ruby"
(required)
--auth_type one of "apikey", "oauth"
(required)
--auth_key auth key
If --auth_type=apikey, pass API Key
If --auth_type=oauth, pass OAuth Bearer Token
(required)
--json valid JSON file containing all request data
OR base64-encoded JSON string
(required)
--server API server to use, must be like "api.hellosign.com".
(defaults to api.hellosign.com)
--uploads_dir directory where files that can be uploaded to the API live.
(defaults to /Users/jtreminio/www/hellosign/openapi/sdk-tester/file_uploads)
--dev_mode run container in dev mode
(optional, default false)
--help display this help and exitThe command to run each script is identical to each other, and they all require the same flags to function correctly.
install pytest using below command
pip3 install pytestTo run all the tests under the tests/ folder
pytest -svra tests/ To run individual tests from a file.
pytest -svra tests/test_signature_request.py::test_signature_request_sendTo run tests in individual environment in QA env To run on staging pass SERVER = api.staging-hellosign.com and appropriate API_KEY
LANGUAGE=python API_KEY=<API_KEY> SERVER=api.qa-hellosign.com pytest -svra tests/test_template.py::test_get_templateOne of dotnet, java, node, php, python, ruby.
Currently we support API key apikey or OAuth bearer token oauth
If auth type (--auth_type) is apikey this will be the API Key.
If auth type (--auth_type) is oauth this will be the OAuth bearer token.
A local file containing the JSON data sent in the request to the API, OR a base64-encoded string containing the JSON data sent in the request to the API.
See the JSON Data section for more information.
What server to make the API request to. For example, api.hellosign.com.
Local directory containing any files you would want to upload in the API request.
Defaults to ./file_uploads.
Runs the container in dev mode. Simply calling --dev_mode enabled Dev mode,
there is no need to pass a value to it. It is disabled by default.
Dev mode adds a cookie XDEBUG_SESSION=xdebug to the request that allows
debugging the API backend.
It also loads the local requester.* file into the container, overwriting the
file that was baked into the image during the build step.
Dev mode is extremely useful when you want to debug the request via the API
backend, or want to make changes to the requester.* file locally and test them
out without needing to rebuild the container image.
Using Dev mode you can also change request data (sent to the API) by editing the data.json file that is generated after running a build script. Changes to this file are ignored by git.
Whether using a local file or a base64-encoded string for the JSON payload it must match the following shape:
{
"operationId": <string> (required),
"data": <object>,
"parameters": <object>,
"files": <object>
}
This is a string that must match one of the operationId values within the
OpenAPI spec's paths object.
In the example below, the operationId value is accountCreate:
paths:
/account/create:
post:
tags:
- Account
summary: 'Create Account'
description: 'Creates a new Dropbox Sign Account that is associated with the specified `email_address`.'
operationId: accountCreate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreateRequest'
examples:
default_example:
$ref: '#/components/examples/AccountCreateRequestDefaultExample'
oauth:
$ref: '#/components/examples/AccountCreateRequestOAuthExample'The data to be sent to the API in the body of the request. Must be an object.
If the API endpoint you want to use has query parameters, you must define them here.
For example, GET /account has a account_id query parameter.
If the API endpoint you want to use allows uploading files, you must define them here.
The file you want to use must be found in the file_uploads directory!
If the endpoint supports multiple files you must pass a nested object.
{
"operationId": "accountGet",
"parameters": {
"account_id": "5d38f3a287c072a2ac741191c5c055936a56b933"
},
"data": {},
"files": {}
}{
"operationId": "apiAppCreate",
"parameters": {},
"data": {
"name": "My Production App",
"callback_url": "https://example.com/callback",
"domains": [
"example.com"
],
"oauth": {
"callback_url": "https://example.com/oauth",
"scopes": [
"basic_account_info",
"request_signature"
]
},
"options": {
"can_insert_everywhere": true
},
"white_labeling_options": {
"header_background_color": "#1A1A1A",
"legal_version": "terms1",
"link_color": "#00B3E6",
"page_background_color": "#F7F8F9",
"primary_button_color": "#00b3e6",
"primary_button_color_hover": "#00B3E6",
"primary_button_text_color": "#ffffff",
"primary_button_text_color_hover": "#FFFFFF",
"secondary_button_color": "#FFFFFF",
"secondary_button_color_hover": "#FFFFFF",
"secondary_button_text_color": "#00B3E6",
"secondary_button_text_color_hover": "#00B3E6",
"text_color1": "#808080",
"text_color2": "#FFFFFF"
}
},
"files": {
"custom_logo_file": "pdf-sample.pdf"
}
}{
"operationId": "signatureRequestSend",
"parameters": {},
"data": {
"cc_email_addresses": [
"lawyer@hellosign.com",
"lawyer@example.com"
],
"message": "Please sign this NDA and then we can discuss more. Let me know if you\nhave any questions.",
"signers": [
{
"email_address": "s1@example.com",
"name": "Signer 1",
"order": 0,
"sms_phone_number": "+14155550100",
"sms_phone_number_type": "delivery"
}
],
"subject": "The NDA we talked about",
"test_mode": true,
"title": "NDA with Acme Co."
},
"files": {
"files": [
"pdf-sample.pdf",
"pdf-sample-2.pdf"
]
}
}All responses will match the following shape, whether the response was successful or resulted in an error:
{
"body": <object>,
"status_code": <integer>,
"headers": <object>
}
This is an example of a successful API response:
{
"body": {
"account": {
"account_id": "0f7cfef800c571173e5fec744bce8b27c3f30569",
"email_address": "signer2@hellosign.com",
"is_locked": false,
"is_paid_hs": false,
"is_paid_hf": false,
"quotas": {
"api_signature_requests_left": 0,
"documents_left": 3,
"templates_left": 0
},
"locale": "en-US"
}
},
"status_code": 200,
"headers": {
"date": "Tue, 26 Jul 2022 15:16:17 GMT",
"server": "Apache",
"x-powered-by": "PHP\/7.4.28",
"x-robots-tag": "noindex",
"x-ratelimit-limit": "10000",
"x-ratelimit-limit-remaining": "9999",
"x-ratelimit-reset": "1658848577",
"access-control-allow-origin": "*",
"access-control-allow-headers": "Authorization, Origin, X-Requested-With, Content-Type, Accept",
"access-control-allow-methods": "GET, POST, OPTIONS",
"user-agent": "Dropbox Sign API",
"vary": "Accept-Encoding",
"strict-transport-security": "max-age=15768000",
"p3p": "CP=\"NOP3PPOLICY\"",
"content-length": "360",
"connection": "close",
"content-type": "application\/json"
}
}Note that header names are all lowercased!
This is an example of a unsuccessful API response:
{
"body": {
"error": {
"error_msg": "Unauthorized api key",
"error_name": "unauthorized"
}
},
"status_code": 401,
"headers": {
"date": "Tue, 26 Jul 2022 15:23:38 GMT",
"content-type": "application\/json",
"content-length": "74",
"connection": "keep-alive",
"server": "Apache",
"strict-transport-security": "max-age=31536000",
"vary": "Origin",
"x-robots-tag": "noindex",
"access-control-allow-origin": "*",
"access-control-allow-headers": "Authorization, Origin, X-Requested-With, Content-Type, Accept, Request-URL, Referrer-Policy, Referer, Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-Fetch-Site, User-Agent, X-User-Agent",
"access-control-allow-methods": "GET, POST, OPTIONS, PUT, DELETE",
"user_agent": "Dropbox Sign API",
"p3p": "CP=\"NOP3PPOLICY\""
}
}Note that header names are all lowercased!
The following are some examples with all required flags.
./run \
--sdk=php \
--auth_type=apikey \
--auth_key=4e0a8a8bd9fea228a1de515a43a75ded2e495471b830069cc8e1821c13c31ce4 \
--json="${PWD}/test_fixtures/accountCreate-example_01.json"./run \
--sdk=node \
--auth_type=apikey \
--auth_key=4e0a8a8bd9fea228a1de515a43a75ded2e495471b830069cc8e1821c13c31ce4 \
--json="ewogICJvcGVyYXRpb25JZCI6ICJhY2NvdW50Q3JlYXRlIiwKICAicGFyYW1ldGVycyI6IHt9LAogICJkYXRhIjogewogICAgImVtYWlsX2FkZHJlc3MiOiAic2lnbmVyMUBoZWxsb3NpZ24uY29tIgogIH0sCiAgImZpbGVzIjoge30KfQo="Unless otherwise noted:
Copyright (c) 2023 Dropbox, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.