Sync-Ends

Table of Contents

• Overview
• Features
• Architecture Diagram
• How to Setup
• Config file Setup
• Prerequisites
  • Step 1: Setup Postman
  • Step 2: Create a Slack workspace and integrate Slack bot
    • 2a. Creating Slack workspace
    • 2b. Creating Slack bot
• Code Documentation
• License

Overview

Sync-Ends is a productivity service, an automated bridge to sync service owners and service consumers that focuses on saving developer time by automatically notifying API consumers when a change is made in the API.

With more and more teams working autonomously and focusing on a microservice and API-driven culture, it is a hassle, for the API developers to keep notifying their consumers of API changes, and for the API consumers to keep track of these API changes and make required changes in their codebase.

Sync-Ends service addresses this problem by taking the hassle away from the API developers and consumers. The Sync-Ends service continuously monitors the API collection in Postman (being worked on by API developers) and every time an API changes in this collection, it notifies a slack channel (followed by the API consumers) with a diff of the change. This way, API developers don't need to manually post messages every time something changes in the service and API consumers are sure that they are utilising the latest API changes.

Take a look at this short video to understand the project idea better.

Features

Feature	Description
1-step service execution	Simple 1-step CLI execution for Sync Ends service
API Change Notification	Get notifications about changes made to the API in Postman along with detailed diff of changes
Track Postman collection	Ability to track a Postman collection and get notifications
Slack Bot Subscription	Set frequency of notifications as well as customize Slack channel for updates

Architecture Diagram

How to Setup

1. Perform the steps described in the Prerequisites section.
2. Install python 3.
3. To install packages, run: pip install -r requirements.txt
4. Create a config json file to be used by the Sync Ends service. Refer to the config file setup section for details.
5. Run the service using: python src/main.py --config <config-file-path>

Config file Setup

The sync-ends service uses a configuration file to configure postman token, slack channels and other parameters required to run the service. The file format must be .json. Here's how the config file looks like:

{
    "postman_api_key": "<a>",
    "slack_token": "<b>",
    "trigger_interval": <c>,
    "collections": [
        {
            "collection_name": "<d>",
            "slack_channel": "<e>"
        }
    ]
}

where,

• a: postman api key generated using steps shown in Postman Setup section.
• b: slack token generated using steps shown in Slack Setup section.
• c: [optional: default=10] time (in seconds), after which application will periodically check for api changes
• d: collection name from postman collections
• e: [optional: default="general"] slack channel in which notifications will be sent (must be a public channel)

Prerequisites

Step 1: Setup Postman

1. Sign in to Postman.
2. If you do not have any pre-exiting collections on Postman, import this sample collection.
3. To integrate with the Sync Ends service, a Postman API key is required. Generate API key by visiting this page.
4. Copy the generated API key. This is required during the time of execution of the service. Make sure you store it safely as you won't be able to view this any other time.

Step 2: Create a Slack workspace and integrate Slack bot

2a. Creating Slack workspace

1. Open https://slack.com/.
2. Provide your email ID. Select Create New workspace.
3. Check your email and enter the code to verify your email.
4. Provide your name and set a password.
5. Add some details to your workspace in the next page.
6. Provide a company name.
7. Workspace URL should be unique. Also remember this URL, this is what is used to login to your Slack instance.
8. Agree with the terms.
9. Skip the invite step.
10. You are up and running with your own instance of Slack.

2b. Creating Slack bot

1. Open your <workspace-URL>/apps (the one you created above). For example, https://test-visual.slack.com/apps.
2. Search for bot in the search bar and select Bots.
3. In the Bots landing page, click on Add configuration.
4. Provide a Bot name. For example, wolfpack-bot and click on Add Bot integration.
5. In the Setup instruction page: Copy and store the API Token. For example, the token may look something like this: xoxb-22672546-n1X9APk3D0tfksr81NJj6VAM.
6. Save the Bot integration.

Code Documentation

The documentation for the code classes and methods is generated using pdoc3. To view this documentation, clone the repo and navigate to docs/src/ and open index.html in a browser.

License

This project is licensed under the MIT License.