Getting Started with the Construct API: Making Your First Request

Screen Shot 2014-06-06 at 8.37.31 AMHundreds of government agencies across the United States and the world are using Accela Automation to streamline and manage their operations.  With the Construct API, Accela is changing the game by enabling developers a way to connect to these agencies providing Land ManagementLicensing & Case ManagementAsset Management, Legislative Management, and Public Health and Safety services to their citizens.  We are seeing incredible creativity and innovation from developers as they extend and create new solutions on the Accela Platform.

Getting started with the Construct API is easy!  In this post we will take you through the steps to make your first request using the Construct API and get you on your way to developing the next great civic app!  If you are new to APIs no problem, check out this post before you get started: Free Guide to Learning Web APIs.

Get Signed Up on the Accela Developer Portal

First things first, let’s get signed up on the Accela Developer Portal.  The portal hosts many great resources including: API documentation, mobile SDK downloads, access to an Accela Automation sandbox environment for developers, and registration/management for applications you build for the Accela Platform.

Register Your First Application

Once registered and logged in you can now add your first app!  Under ‘My Apps’ click the button ‘Add New App’, you will be presented with a form needing some basic details about your app.

Add New App

Add New App Form

  • Targeted Users: Your options are ‘Citizen’ and ‘Agency’, this determines the authentication path and available APIs to which you can use.  Agency apps are intended for government users of Accela Automation and require an existing login within the back office system.  Citizen apps are for public usage to enable citizens to engage with their governments.
  • App Name: The name of your app
  • App Description: A brief summary description of your app
  • Stage: Your options are ‘Under Development’ and ‘Published’.  Your app will be set to ‘Under Development’ until your is app ready to be launced.
  • Authorized Redirect URIs: Used within your authentication implementation to specify authorized redirect URIs to add appropriate security.

Fill out these basic details and click ‘Submit’.  Congratulations, you now have a registered app on the Accela Platform!  Going through these steps gets app your app assigned an App ID and an App Secret, we’ll need these for both authentication and API requests.  You will also receive an email with these details.

Getting a Test API Token

As you get familiar with the Construct API documentation you will see that each request has a specified Authorization Type.  This tells us what headers we need to send with our API request.  One of these authorization types requires us to include an ‘Access Token’.  The access token is granted upon successful authentication as either a citizen or agency user (Learn more about CivicID) and makes sure our communication with Accela Automation is secure.

Since we are working on our first API request in this post and have not yet set up authentication in our app we will use a nice utility in the developer portal to request a test API token.  You will find the link to request a test API token (you are required to be logged in) under the ‘Test Resources’ section of the API documentation along with credentials you can use to log into our sandbox.

During the request flow you will be prompted for a few details in addition to a username and password.

Get API Test Token

Get API Test Token

  • Client (My App): Make sure the app that you registered previously is selected.
  • Environment: This is hard coded to ‘TEST’ and designates which agency environment we will authenticate with.  The developer sandbox is considered a test environment.
  • Agency Name: The id that an agency has registered on the Civic Platform with, for our tests the sandbox id we will use is prefilled.
  • Scope: This is a space delimited list of the API requests you plan to use.  Go ahead and enter ‘get_records’ for the ‘Scope’.

The above details are usually implemented in your app as a part of the OAuth2 authentication implementation.  Click ‘Submit’ to continue.

We are now prompted for a username and password.  Use the credentials provided in the Testing Resources section of the API documentation and click ‘Sign In’ (you must be logged into the developer portal to access this information).

Screen Shot 2014-06-06 at 9.11.29 AM

Allow Access

You will prompted to allow access for this app and following a successful authentication you will see a text box containing a long string of letters, numbers and symbols.  This is your test API token, be sure to leave this open in a tab, copy to your clipboard or paste it into a text file, we will need this in a moment.

Making Your First Request

We now have everything we need to make our first Construct API request.  For this example we will requesting a list of records within the agency and playing around a bit with some request parameters.  A Record in Accela Automation represents things like permits, licenses, complaints, work orders, cases and many other transactional processes.  First check out Get All Records in the API documentation.

To initiate our API request I’ll be using a really nice app in Chrome called Postman, a really useful tool if you do a lot of work with APIs.

Postman - Rest API Client

Postman – Rest API Client

First we will need to provide the request URL.  The endpoint for all Construct API requests is: https://apis.accela.com.  A really powerful feature of the Construct API is that no matter what government agency you are working with you alway point to the same URL!  Check out this post to learn more about the architecture behind the Construct API: Under the Hood: the Accela Construct API.

To target a specific API all we need to do is add the URI from the documentation to the end of the URL.  The below is the URI for the get_all_records request.

/v4/records?type={type}&openDateFrom={openDateFrom}&openDateTo={openDateTo}&customId={customId}&module={module}&status={status}&statusDateFrom={statusDateFrom}&statusDateTo={statusDateTo}&assignDateFrom={assignDateFrom}&assignDateTo={assignDateTo}&completeDateFrom={completeDateFrom}&completeDateTo={completeDateTo}&completeDepartment={completeDepartment}&completeStaff={completeStaff}&closedDateFrom={closedDateFrom}&closedDateTo={closedDateTo}&closedDepartment={closedDepartment}&closedStaff={closedStaff}&limit={limit}&offset={offset}&fields={fields}&lang={lang}

Everything listed after the question mark is referred to as request parameters and in the context of get_all_records they will contain any search filters we would like to limit the data that is returned in response to our request.

Let’s start with this URL for our example:

https://apis.accela.com/v4/records?openDateFrom=2014-05-01&openDateTo=2014-06-05

Copy and paste the above to the Request URL field in Postman.  Next let’s take a look at the request Headers.  Click the Headers button and add the following:

  • Content-Type = application/json
  • Accept = application/json
  • x-accela-appid = [Enter your App ID that was generated when registering your app]
  • Authorization = [Enter the API token that was generated through the test token process]

Finally make sure that the request method is set to ‘GET’ in a dropdown left of the ‘URL Params’ button.  That’s it!  Click the ‘Send’ button to initiate your request and the results will display in the lower panel.  Congratulations, you have initiated your first request using the Construct API!  Have some fun and play around with some different parameters and see what is returned, here are some more examples.

Search by module: https://apis.accela.com/v4/records?module=Building

Search by module and application status: https://apis.accela.com/v4/records?module=Building&status=Submitted

Search by module, application status and date opened range: https://apis.accela.com/v4/records?openDateFrom=2014-05-01&openDateTo=2014-06-05&module=Building&status=Submitted

When you are ready take a look at some other Construct APIs, remember you will need to request a new test API token with additional scope specified for any new API calls you will be initiating.  Good luck and happy hacking!

 

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s