When I get on a call with a prospective app developer or someone interested in becoming a certified developer, there are a number of development principles that we usually touch on. Making our app partners and certified developers successful on NationBuilder helps our customers be successful in their organizing efforts. To make sure everyone has access to these principles I’ve outlined them below:
Make your data actionable
Data transfers between third-party apps and a nation are some of the most common integrations in our directory. Usually, that data is captured because an action has occurred on another system and the customer wants to be able to use the fact that action occurred to segment the data in their nation.
Knowing how someone entered their nation is critical to our customers knowing how to engage them. That is why we encourage developers to use certain methods of making supporter actions discoverable:
- Lists API
- Writable tag resources
- Contacts API
This way customers can identify supporters who take actions by using the powerful filtering tools provided in NationBuilder.
An example of actionable data can be seen with integrations like DoGooder, an email advocacy tool. Supporters who complete a DoGooder action will enter the NationBuilder database as a standard signup record (name, email, phone number) with a tag that follows the format: dogooder-campaign name-date of action
Customers can easily filter for supporters who took the action. The same can be accomplished by adding all supporters to a list or by logging the action as a contact in the control panel.
Implement OAuth
OAuth is required if you want to have your app listed in the app directory. Nationbuilder currently uses OAuth 2.0 which allows your application to receive an access token from a nation programmatically.
Using OAuth allows people who use NationBuilder to easily and securely add your app to their nation, and to revoke that access if they feel the need. You can learn more about the OAuth workflow in our Quickstart Guide.
Respect your rate limits
There is only one rate limit to keep in mind - the per access-token rate limit. This rate limit allows you to hit our API with 100 requests per 10-second interval. Note that you can use an exponential backoff strategy to get past a rate limit once the rate limit interval has passed by setting the `retries` parameter.
Participate in the community
We want to provide an open ecosystem to app partners and certified developers. Our API documentation is the best place to start whether you’re just learning, or if you’ve run into a problem that you’re trying to unravel.
Beyond the docs there are many places for you to contribute, and ask for help including:
-
a public organization on Github where we accept pull requests
-
a public Slack team that is available to all app partners and certified developers (please email [email protected] for access)
-
a developer forum to crowdsource answers to problems and to report issues you’re experiencing with the API
-
sample code to get you started developing with our API
-
and a public Facebook group to facilitate communication between developers and the rest of our ecosystem.
