Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Header information #83

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Header information #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
edc6211
Add Accept header to all examples
WouterJanson Jan 9, 2020
669fcce
Add information about default headers
WouterJanson Oct 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 29 additions & 9 deletions _data/api-swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,34 @@ schemes:
produces:
- application/json
parameters:
AppkeyParam:
name: Application
description: The APPKey
AcceptHeader:
name: Accept
in: header
type: string
required: true
ApiKeyParam:
default: application/vnd.signhost.v1+json
Copy link
Collaborator

@ATimmeh33 ATimmeh33 Oct 14, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think default might be confusing, because:

  1. it MUST be explicitly to use new features like the authentication array
  2. this is only valid for JSON

Let's leave this open and see @MrJoe 's thoughts on this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. this is only valid for JSON

Yes, that's why this parameter is only added to specific endpoints in the swagger file, so in that case default would make sense and it's also the way to add a value according to the spec. (Which I broke in the previous version of this PR 😅)

However I do agree that it might be confusing phrased in the documentation page itself.

description: |
The Signhost API version number.
Used for endpoints that produce JSON output.

securityDefinitions:
AppKeyHeader:
name: Application
type: apiKey
in: header
description: |
The appkey that is generated at signup.
The value must be formatted as: `APPKey {Appkey}`
ApiKeyHeader:
name: Authorization
description: The usertoken
type: apiKey
in: header
type: string
required: true
description: |
Your usertoken, can be generated in the Signhost portal.
The value must be formatted as: `APIKey {usertoken}`

security:
- ApiKeyHeader: []
AppKeyHeader: []

paths:
'/api/transaction/{transactionId}':
Expand All @@ -32,6 +48,7 @@ paths:

Please do not use any GET method for active polling, but use our [postback service](/postback/) for this end.
parameters:
- $ref: '#/parameters/AcceptHeader'
- name: transactionId
description: ID of the transaction
in: path
Expand Down Expand Up @@ -59,6 +76,7 @@ paths:
When a transaction is in an end-state the transaction the transaction will be cleaned.
The status of the transaction will remain the same but we will clean any uploaded documents and sensitive data as soon as possible.
parameters:
- $ref: '#/parameters/AcceptHeader'
- name: transactionId
type: string
description: ID of the transaction
Expand Down Expand Up @@ -126,6 +144,7 @@ paths:
post:
description: Creates a new transaction
parameters:
- $ref: '#/parameters/AcceptHeader'
- in: body
name: transaction
description: Transaction to be added
Expand Down Expand Up @@ -159,6 +178,7 @@ paths:
- 'application/pdf'
- 'application/json'
parameters:
- $ref: '#/parameters/AcceptHeader'
- name: transactionId
description: ID of an existing -- not yet started -- transaction
in: path
Expand Down Expand Up @@ -264,7 +284,7 @@ definitions:
Authentications must be performed before the document(s) can be viewed.

You **must** explicitly specify the API-version when using this feature.
This is done with the header: 'Accept: application/vnd.signhost.v1+json'.
This is done with the <a href="/##/parameters/AcceptHeader">Accept header</a>: 'Accept: application/vnd.signhost.v1+json'.
type: array
items:
$ref: '#/definitions/Authentication'
Expand Down
5 changes: 5 additions & 0 deletions _data/endpoint_examples.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ get/api/transaction/{transactionId}:
curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
-H "Accept: application/vnd.signhost.v1+json" \
https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57
json_response: get_api_transaction_transactionId.json
response_information: This method returns a transaction.
Expand All @@ -27,6 +28,7 @@ post/api/transaction:
curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
-H "Accept: application/vnd.signhost.v1+json" \
-H "Content-Type: application/json" \
-d '{
"Signers": [
Expand Down Expand Up @@ -69,6 +71,7 @@ put/api/transaction/{transactionId}/file/{fileId}:
curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
-H "Accept: application/vnd.signhost.v1+json" \
-H "Content-Type: application/pdf" \
-H "Digest: SHA-256=HtHRpLOZBEMnTpQS6Zn12veC4uhjtMwamfVAwmPQPmE=" \
-XPUT \
Expand All @@ -80,13 +83,15 @@ put/api/transaction/{transactionId}/start:
curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
-H "Accept: application/vnd.signhost.v1+json" \
https://api.signhost.com/api/transaction/b2a9aca4-cd5e-4a21-b7f7-c08a9f2b2d57/start
delete/api/transaction/{transactionId}:
- example:
curl_request: |
curl \
-H "Authorization: APIKey {usertoken here}" \
-H "Application: APPKey {appkey here}" \
-H "Accept: application/vnd.signhost.v1+json" \
-H "Content-Type: application/json" \
-d '{
"SendNotifications": true
Expand Down
39 changes: 39 additions & 0 deletions _includes/httpheaders.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<!-- Begin list of HTTP headers-->
<table>
<thead>
<tr>
<th>Name</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<!-- Parameters -->
{% for p in site.data.api-swagger.parameters %}
{% for parameter in p %}
{% assign parameter = p[1] %}
{% if parameter.in == 'header' %}
<tr id="#/parameters/{{ p[0] }}">
<td>{{ parameter.name }}</td>
<td>{{ parameter.default }}</td>
<td>{{ parameter.description }}</td>
</tr>
{% endif %}
{% endfor %}
{% endfor %}
<!-- security -->
{% for sd in site.data.api-swagger.securityDefinitions %}
{% for parameter in sd %}
{% assign parameter = p[1] %}
{% if parameter.in == 'header' %}
<tr>
<td>{{ parameter.name }}</td>
<td>{{ parameter.default }}</td>
<td>{{ parameter.description | markdownify}}</td>
</tr>
{% endif %}
{% endfor %}
{% endfor %}
</tbody>
</table>
<!-- End list of all HTTP headers -->
28 changes: 15 additions & 13 deletions endpoints.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,19 +60,21 @@ <h3>Parameters</h3>
<tbody>

{% for p in method.parameters %}
<tr>
<td>{{ p.name }}</td>
<td>{{ p.in }}</td>
<td>{{ p.required }}</td>
<td>{{ p.description }}
{% if p.schema["$ref"] %}
<a href="#{{ p.schema["$ref"] | uri_escape }}">
{{ p.schema["$ref"] }}
</a>
{% endif %}

</td>
</tr>
{% if p["$ref"] == null %}
<tr>
<td>{{ p.name }}</td>
<td>{{ p.in }}</td>
<td>{{ p.required }}</td>
<td>{{ p.description }}
{% if p.schema["$ref"] %}
<a href="#{{ p.schema["$ref"] | uri_escape }}">
{{ p.schema["$ref"] }}
</a>
{% endif %}

</td>
</tr>
{% endif %}
{% endfor %}
</tbody>
</table>
Expand Down
3 changes: 3 additions & 0 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ A name for the usertoken has to be submitted, after which the value for this use
The amount of usertokens that can be generated for an account is limited to 64.
If more usertokens are needed, this needs to be requested at support@signhost.com.

### HTTP Headers
{% include httpheaders.html %}

Below you find a HTTP request header example:

Content-Type: application/json
Expand Down