dweetPro.io User Manual
https://dweetPro.io - Ridiculously simple messaging for the Internet of Things. Now with enterprise features!
dweetPro combines the simplicity of dweet.io with new, easy-to-use APIs for storage, device management, alerts/notifications and reporting.
Available below is a step-by-step getting started guide, as well as a glossary to help users hit the ground running.
Sign Up for a free account and follow the instructions below.
-
If you haven't already, sign up for a free account and login
-
Navigate to the Collections page, and create a new Collection by clicking the +Collection button
-
Provide a name for your Collection (we chose "My_Collection"), and click the Add button
-
Your Collection will now appear in the Collection list. Click on the Collection you just created
-
Click the +Thing button to create a Thing
-
Name your Thing something fancy like 'thing_name1'. If you have an available Lock (new sign-ups get 1 free!) it will automatically be assigned to your Thing.
-
Click your newly-created Thing
-
The Thing Details page allows you to view and manage all meta data, Lock-related credentials, and Alerts for a Thing.
-
For this tutorial, take note of the Master Key, which will allow us to send dweets using the POST /v2/dweets API. The Master Key can be used for all thing-related requests, whereas the Read-only key is limited to certain GET requests.
-
We now need to grab our Account Token (aka Thing Token), from the Accounts -> Organization page. This will be the value of the X-DWEET-AUTH header set in our send requests.
- Click the copy icon to copy the Thing Token to your clipboard (and paste in the scratchpad you made in Step 9, if you have one)
- We now have all of the credentials necessary to send our first dweet! To make testing quick-and-easy, we have provided a Swagger-based API request tool available from the Console page.
- On the Console page, navigate down to the 'dweets' section and expand the '/v2/dweets' API. (NOTE: You will notice a value already provided in the X-DWEET-AUTH field. This is the Master Token generated for this session while logging in to the management UI. We will replace this with our Thing Token in later steps)
- To make things even easier, Click the Model Schema link, then click inside the yellow Model Schema box. This will automatically generate the basic key fields for the /v2/dweets request in the payload testing area to the left.
- Fill in the values obtained in Steps 8 & 9 for the "thing" and "key" fields, and provide a valid JSON object as the value for the "content" field.
- Click the "Try it Out!" button, and review the Response Body section to verify the request succeeded. If the request fails, any errors will be reported in this area.
- Finally, we will test the request again using our Thing Token, obtained in Step 11. Click the console token switch in the top right corner of the page.
- You will notice the X-DWEET-AUTH value is now blank. Paste the Thing Token retrieved in Step 11, and click the "Try it out!" button.
Congratulations! You have now sent your first couple of dweets. Please review the Key Concepts section below for more in-depth information on all of Dweet Pro features, concepts and terminology.
In contrast to our our original API set (now known as our Public APIs), data and assets using the Pro APIs benefit from expanded security and access control. As such, you will need to include a token in the header of every Pro API request. We created two types of tokens - the Thing Token and Master Token - with different access control capabilities. Depending on the type of token provided in the request, API access may be further limited by the role of the user - Admin, Manager, or Viewer - that is making the request.
The new (/v2) APIs, which provide enhanced security, management, configuration, storage, and alerting functionality suitable for production-ready development. These APIs can only be used with a Dweet Pro account. Register for a free account at https://dweetpro.io.
Our original, free and “ridiculously simple” API set. Use these APIs to get started working with dweet.io - no signups, no hassle. Data sent through these APIs will appear on our publically accessible discover page.
(The X-DWEET-AUTH header)
In order to use the Pro APIs, you will need to include the header “X-DWEET-AUTH” in every request, with an encoded alphanumeric string value which we call a Token. This allows owners of a Pro account to manage access to the data and the control functionality of the assets associated with their account. In order to provide enhanced security and access control, we created two types of Tokens - the Master Token and Thing Token - which are used in different contexts depending on who or what is making the API call.
The Master Token is a user-level, session-based token made up of approximately 265 alphanumeric characters. Typically used for administrative functionality (which can also be accomplished in the https://dweetPro.io Management UI
- Can provide access to all Pro APIs depending on the user's account type
- Authorization to use different subsets of the Pro APIs is determined by the role of user:
- Admins: Full access
- Managers: Access to MOST APIs, except billing, lock purchasing, and org/account/user creation
- Viewers: limited to read-only fuctionality for Things, Collections and Dweets
NOTE: After logging in to the Management Portal, clicking on the Console page will show only the APIs available to that user.
- Retrieved by issuing a
POST /v2/users/loginwith a username field and password field in the request body.
The Thing Token is a static, restricted, account-wide token, made up of approximately 150 alphanumeric characters. A physical device is best suited to use the Thing Token
- Used for basic communication to/from dweetPro.
- Limited to the following API requests:
POST /v2/dweets
GET /v2/dweets/latest
GET /v2/dweets
GET /v2/dweets/listen
The purpose of the Thing Token is to enable assets that are interested in data messaging APIs - not management functionality - to be able to continuously communicate with the platform. As such, this Token does not expire unless intentionally re-generated by an Admin user (as may be necessary in a situation where the Thing Token is compromised to unauthorized parties).
- Re-generating the Thing Token can be accomplished either through the management UI (in the Organization tab of the Account page), or by issuing a
GET /v2/accounts/token(HINT: this request is made with the X-DWEET-AUTH header set to the Master Token of a logged-in Admin). Proceed with caution: Re-generating the Thing Token will de-authorize the previous Thing Token and all previously locked Things.
Another term for locking a Thing. Provisioned/locked Things can take advantage of long term storage, alerts, and can be organized within a Collection.
A Lock is used to provision a Thing. After applying a Lock to a Thing, data storage and alerting features are enabled for that Thing, as well as the ability to add that Thing to a Collection.
Locks can be purchased and added to an account by Admin users only. Managers can then manage the association of the available Locks to different Things, either by locking unprovisioned things or unlocking already-provisioned things.
Each Lock has three unique characteristics: Lock ID, Master Key and Read Key.
Used to lock a Thing. At any given time, only one lock can be applied to one Thing. The two remain bound together, until an Admin or Manager unlocks that Thing. After unlocking a Thing, the Lock that was associated with that Thing becomes free to use with any unprovisioned Thing in the account.
After locking a Thing, any requests to the /dweets APIs using a Thing Token must also include one of the lock’s Keys as described below.
When a Thing Token is provided in the request header, the Lock’s Master Key can access all Thing Token enabled APIs (POST /v2/dweets, GET /v2/dweets/latest, GET /v2/dweets). This key is typically used to allow an asset to send data to the platform.
When a Thing Token is provided in the request header, the Lock’s Read Key can access only the Thing Token APIs that retrieve data of a thing (GET /v2/dweets/latest, GET /v2/dweets, GET /v2/dweets/listen). Sharing the Read Key along with the Thing Token allows users to provide read-only access of their Things’ latest data to others.
A Collection is a group of locked Things, used for organizational purposes. When locking/provisioning a Thing, it must be added to a Collection. Unlocked/unprovisioned things are held in a special Collection called “UNPROVISIONED”.
Creating a new thing inside of a specific Collection will auto-assign that new thing an Unused Lock. You can unlock a Thing, or Move a Thing from one Collection to another.
Labels are a way to group Things in multiple ways, outside of any Collection restriction. You can use the GET /V2/things/label to see all Things with a certian label.
DweetPro APIs maintain a common RESTful API structure, using the standard HTTP protocol.
The headers of an HTTP request are set separately from the URL of the request.
Standard notation for APIs are to show the relative path to the server, eliminating redundancy in documentation. So, when you see an API displayed as "/v2/login", the full URL is actually "http://dweetpro.io/v2/login".
The current HTTP protocol does not allow you to set the headers within the URL, only parameters. When typing in a URL into a browser, the browser makes an HTTP GET request to the URL, with parameters if they are supplied (e.g. the "?param1=val¶m2=val" part of the URL). Browsers can only make POST requests by using a plugin, like POSTman for Chrome. Again, this is commonplace across all APIs you might encounter. You can consult any resource online for tutorials on the HTTP protocol and making HTTP POST requests from the client of your choice. Most programming languages provide easy ways to set the headers, and the body of an HTTP POST request.