API Development & Maintenance
Feature Releases
Jira Sprints
Jira Sprints will be created and tied to a Jira Release.
Cards will be moved into and out of the Sprint on a regular basis as development progresses and blockages are found and/or cleared.
Cards will be tagged with the release in the “fix_version” field.
The development work will happen in the QA API environment. When the Sprint is complete, the work will be released into the Staging API environment, which users will be able to test against for a period of 2 - 4 weeks. At the conclusion of that period, pending any additional feedback related fixes or retractions, the work will be released into the Production API environment.
Jira Releases
Geopath API releases will be added to the Jira Release page.
Releases within the same version will be dated with the day they are intended to be released into production.
API releases are currently planned on weeks when there is not an API data update, to better insulate each product, and to be able to better identify the source of any issues that arise.
API releases are currently planned on Thursdays to enable initial testing and problem resolution without impacting weekends.
Jira Backlog
Work that has been identified and has had a Jira card created will remain the backlog until it is added to a release Sprint.
Work that is on an existing Sprint may also be moved back to the backlog pending resource allocation.
Jira Visibility
The Jira backlog and active Sprint open / completed issues is accessible to all users without and login here
Data Releases
There are currently three streams of data in the Geopath API. Audience Measures, Inventory and Reference. Each of these data streams is updated at a different cadence.
Reference data is updated rarely as it is the most stable data.
Audience measures are updated on a bi-weekly basis, becoming available as of 10 pm eastern time on Sunday evenings on the release week. This is subject to change as Geopath refines its impression calculation process.
Inventory data is updated on a continuous basis.
This infographic shows a visual breakdown of these timelines:
Calendar
The development calendar can be seen here
Breaking Changes
Geopath and its development partners have built the Geopath API to minimize the need for breaking changes. Generally, the API core functions and data are stable, while new features and data can be added without causing a breaking change.
However, if there is a need to deprecate a specific feature or endpoint while making future updates the following will happen:
The release will be a new public version number of the Geopath API
The previous version will continue to operate for at least 6 months after the date of the new release
The new features or deprecated changes in the existing version will be documented as such with references to the updated location / features in the latest version
The Geopath developer community will be alerted to such a change as part of the monthly release feedback process.
Bugs
API bugs are when a feature or an endpoint is not functioning, or not returning expected results.
Features that are not yet developed or not within the current product roadmap are not considered bugs but can be added to the roadmap or re-prioritized within the roadmap based on feedback from the Geopath developer community
Geopath organizes bugs into 4 priorities
Endpoint not responding and no workaround available.
Endpoint not responding but viable workaround available.
Endpoint / Feature not returning expected results and no workaround available.
Endpoint / Feature not returning expected results but viable workaround available.
Bugs will be addressed by the development team as quickly as possible based on the root cause and released as a ‘hotfix’ to the most recent released version.
Bug Reporting
If you feel you have identified a bug in a Geopath API product please contact Geopath at apisupport@Geopath.org and/or at geekout@Geopath.org as this will ensure it gets seen and communicated to the proper staff.
When reporting a bug please be as detailed as possible about what led you to it. Include the endpoint / feature you are trying to use as well as the call you are trying to make. Include any error messages / failure logs you have received from the API or your application.
Downtime
Geopath utilizes a rolling update procedure to deploy both data and feature updates that aims to eliminate the need for server maintenance-based downtime. However, if there is a need for planned downtime, it will be planned at a time to minimize business disruption and will be communicated as far in advance of the work as possible.
In the case of unplanned downtime, Geopath will aim to notify API users as soon as the outage is discovered and validated and will continue to communicate timelines of a fix and the ultimate resolution of the issue.
Geopath has created a twitter account for the Geopath API to be able to communicate the status of the API. In the event of a broader geopath platform outage the Api twitter feed should still be able to communicate the status of the api. Please follow @geopathapi
Feedback
The Geopath developer community is encouraged to provide feedback whenever possible. Feedback can include questions regarding API usage as well as feature requests that will be evaluated and added to the product roadmap where applicable.
When submitting feedback, please be as detailed as possible in your use case. Please Include the details / body of any calls you are inquiring about. Feedback can be sent to apisupport@Geopath.org