Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

integration guide: Move Hello World walkthrough to end.

This commit is contained in:
Christie Koehler 2016-08-04 15:16:30 -07:00 committed by Tim Abbott
parent 6cf6341a49
commit 4c66bbc1ee
1 changed files with 80 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

156
docs/integration-guide.md
View File

@ -81,7 +81,6 @@ products, ordered here by which types we prefer to write:
spot why something isn't working or if the service is using custom HTTP spot why something isn't working or if the service is using custom HTTP
headers. headers.
## Webhook integrations ## Webhook integrations
New Zulip webhook integrations can take just a few hours to write, New Zulip webhook integrations can take just a few hours to write,
@ -128,6 +127,9 @@ Here's how we recommend doing it:
* Finally, write documentation for the integration; there's a * Finally, write documentation for the integration; there's a
[detailed guide](#documenting-your-integration) below. [detailed guide](#documenting-your-integration) below.
See the [Hello World webhook Walkthrough](#hello-world-webhook-walkthrough)
below for a detailed look at how to write a simple webhook.
### Files that need to be created ### Files that need to be created
Select a name for your webhook and use it consistently. The examples below are Select a name for your webhook and use it consistently. The examples below are
@ -159,6 +161,83 @@ register a url for the webhook of the form `api/v1/external/mywebhook`
and associate with the function called `api_mywebhook_webhook` in and associate with the function called `api_mywebhook_webhook` in
`zerver/views/webhooks/mywebhook.py`. `zerver/views/webhooks/mywebhook.py`.
## Python script and plugin integrations
For plugin integrations, usually you will need to consult the
documentation for the third party software in order to learn how to
write the integration. But we have a few notes on how to do these:
* You should always send messages by POSTing to URLs of the form
`https://zulip.example.com/v1/messages/`, not the legacy
`/api/v1/send_message` message sending API.
* We usually build Python script integration with (at least) 2 files:
`zulip_foo_config.py`` containing the configuration for the
integration including the bots' API keys, plus a script that reads
from this configuration to actually do the work (that way, it's
possible to update the script without breaking users' configurations).
* Be sure to test your integration carefully and document how to
install it (see notes on documentation below).
* You should specify a clear HTTP User-Agent for your integration. The
user agent should at a minimum identify the integration and version
number, separated by a slash. If possible, you should collect platform
information and include that in `()`s after the version number. Some
examples of ideal UAs are:
```
ZulipDesktop/0.7.0 (Ubuntu; 14.04)
ZulipJenkins/0.1.0 (Windows; 7.2)
ZulipMobile/0.5.4 (Android; 4.2; maguro)
```
## Documenting your integration
Every Zulip integration must be documented in
`templates/zerver/integrations.html`. Usually, this involves a few
steps:
* Make sure you've added your integration to
`zerver/lib/integrations.py`; this results in your integration
appearing on the `/integrations` page. You'll need to add a logo
image for your integration under the
`static/images/integrations/logos/<name>.png`, where `<name>` is the
name of the integration, all in lower case.
* Add an `integration-instructions` class block also in the
alphabetically correct place, explaining all the steps required to
setup the integration, including what URLs to use, etc. If there
are any screens in the product involved, take a few screenshots with
the input fields filled out with sample values in order to make the
instructions really easy to follow. For the screenshots, use
something like `github-bot@example.com` for the email addresses and
an obviously fake API key like `abcdef123456790`.
* Finally, generate a message sent by the integration and take a
screenshot of the message to provide an example message in the
documentation. If your new integration is a webhook integration,
you can generate such a message from your test fixtures
using `send_webhook_fixture_message`:
```
./manage.py send_webhook_fixture_message \
--fixture=zerver/fixtures/pingdom/pingdom_imap_down_to_up.json \
'--url=/api/v1/external/pingdom?stream=stream_name&api_key=api_key'
```
When generating the screenshot of a sample message, give your test
bot a nice name like "GitHub Bot", use the project's logo as the
bot's avatar, and take the screenshots showing the stream/topic bar
for the message, not just the message body.
When writing documentation for your integration, be sure to use the
`{{ external_api_uri }}` template variable, so that your integration
documentation will provide the correct URL for whatever server it is
deployed on. If special configuration is required to set the SITE
variable, you should document that too, inside an `{% if
api_site_required %}` check.
## `Hello World` webhook Walkthrough ## `Hello World` webhook Walkthrough
Below explains each part of a simple webhook integration, called **Hello Below explains each part of a simple webhook integration, called **Hello
@ -504,79 +583,4 @@ request:
If you would like feedback on your integration as you go, feel free to submit If you would like feedback on your integration as you go, feel free to submit
pull requests as you go, prefixing them with `[WIP]`. pull requests as you go, prefixing them with `[WIP]`.
## Python script and plugin integrations
For plugin integrations, usually you will need to consult the
documentation for the third party software in order to learn how to
write the integration. But we have a few notes on how to do these:
* You should always send messages by POSTing to URLs of the form
`https://zulip.example.com/v1/messages/`, not the legacy
`/api/v1/send_message` message sending API.
* We usually build Python script integration with (at least) 2 files:
`zulip_foo_config.py`` containing the configuration for the
integration including the bots' API keys, plus a script that reads
from this configuration to actually do the work (that way, it's
possible to update the script without breaking users' configurations).
* Be sure to test your integration carefully and document how to
install it (see notes on documentation below).
* You should specify a clear HTTP User-Agent for your integration. The
user agent should at a minimum identify the integration and version
number, separated by a slash. If possible, you should collect platform
information and include that in `()`s after the version number. Some
examples of ideal UAs are:
```
ZulipDesktop/0.7.0 (Ubuntu; 14.04)
ZulipJenkins/0.1.0 (Windows; 7.2)
ZulipMobile/0.5.4 (Android; 4.2; maguro)
```
## Documenting your integration
Every Zulip integration must be documented in
`templates/zerver/integrations.html`. Usually, this involves a few
steps:
* Make sure you've added your integration to
`zerver/lib/integrations.py`; this results in your integration
appearing on the `/integrations` page. You'll need to add a logo
image for your integration under the
`static/images/integrations/logos/<name>.png`, where `<name>` is the
name of the integration, all in lower case.
* Add an `integration-instructions` class block also in the
alphabetically correct place, explaining all the steps required to
setup the integration, including what URLs to use, etc. If there
are any screens in the product involved, take a few screenshots with
the input fields filled out with sample values in order to make the
instructions really easy to follow. For the screenshots, use
something like `github-bot@example.com` for the email addresses and
an obviously fake API key like `abcdef123456790`.
* Finally, generate a message sent by the integration and take a
screenshot of the message to provide an example message in the
documentation. If your new integration is a webhook integration,
you can generate such a message from your test fixtures
using `send_webhook_fixture_message`:
```
./manage.py send_webhook_fixture_message \
--fixture=zerver/fixtures/pingdom/pingdom_imap_down_to_up.json \
'--url=/api/v1/external/pingdom?stream=stream_name&api_key=api_key'
```
When generating the screenshot of a sample message, give your test
bot a nice name like "GitHub Bot", use the project's logo as the
bot's avatar, and take the screenshots showing the stream/topic bar
for the message, not just the message body.
When writing documentation for your integration, be sure to use the
`{{ external_api_uri }}` template variable, so that your integration
documentation will provide the correct URL for whatever server it is
deployed on. If special configuration is required to set the SITE
variable, you should document that too, inside an `{% if
api_site_required %}` check.