The first step is to get an Ensign API key by visiting the sign-up page . Similar to getting a developer API key for Youtube or Data.gov , you will need an API key to use Ensign and to follow along with the rest of this Quickstart guide.
Step 1. Create a New Ensign Project
- After creating an account, click the
Set Up a New Project.
- Enter a
Project Name(required) and provide an optional description, then click
Create Project. You will be redirected to the Projects dashboard.
- For more details, watch the Project Creation Tutorial
Step 2. Create Ensign Topics
- On the Project dashboard, click on your Project Name.
New Topicand enter a Topic Name (required), then click
- For more details, watch the Topic Creation Tutorial
- Pick a name for each topic that encodes information about the data you intend to store in that topic.
- You can also include information about the data format (e.g. flights-json or hotels-html). Read more here
- Topics can help serve as a data contract helping upstream publishers remember how to serialize the data and downstream subscribers how to parse it. Step 3. Create Ensign API Keys
- Click the
- Create a name for the key and select its permissions (Full Access or Custom Access), then click
Generate API Key.
- Copy or download the
Client IDand the
Client Secret, you will need both to connect to Ensign. Read more here
- For more details, watch the API Key Creation Tutorial
- Do not share your keys with anyone, and never commit them to a public GitHub repository. Read more about best practices for API keys here .
- If your keys get lost or compromised, don’t worry, you can revoke them and create new ones.
- API keys grant access to all topics in the project.
- Team members with the
Adminrole can create API keys, an
Observercan not create API keys.
Ensign API Keys
An API key consists of two parts, a
ClientID and a
ClientID uniquely identifies a project, and the
ClientSecret allows you to create and access event data within that project.
|API Key Component Name
|alphabetic (no digits)
ClientSecret provide access to a project. They enable you to create Ensign topics, publishers, and subscribers, which will be the building blocks of your microservice! Anybody with the
ClientSecret has access to your project, so these values should be kept private and not shared.
The SDKs are where you use your API key and allow you to integrate Ensign into your projects. There are currently two SDKs supported.
Using the SDKs requires authenticating with your API key. By default the SDKs will read the Client ID and Client Secret from your environment.
Publish and Subscribe
The most common use of the SDKs is to publish events to topics, and subscribe to events from somewhere else. Topics can be created from your dashboard or directly from the SDKs. See the SDK guides for a quick example of how to get started.