The Challenge: A Disjointed Process
Developers are a valuable - and expensive - enterprise resource. Ensuring developers have the tools they need to be efficient can be challenging but immensely beneficial. This is the challenge that a digital agriculture company sought to tackle.
Their flagship product uses field data to help farmers make better, more informed decisions about their crops. Collecting data from machinery and satellites, the platform’s goal is to be the go-to place for agricultural data. Using APIs, internal and external engineers can access the data, for example, to integrate with and inform third-party applications. However, this process was challenging. The organization needed a way to ease adoption and utilization of the platform, making it easier to get agricultural data to those who needed it. As they move to consolidate tools and update legacy systems in their environment, they wanted a unified API to access this data with a cost effective, efficient process for developers.
Our Process: Human-Centered Design Agile
Leveraging our HCDAgile process, we collaborated closely with multiple teams across the organization. Conducting over 30 interviews, we identified three primary personas representing the users most impacted by the work. Journey maps articulated the process, challenges, and pain points for those users. Story mapping engaged stakeholders in clearly articulating a vision for the solution, obtaining consensus across groups, and prioritizing work.
Iteratively, we gathered actionable feedback from the primary personas on the user experience to ensure the solution met their needs. Having the developers participate in the process helped build understanding of and engagement in shifting the development paradigm.
The Solution: Applying DevOps
The API spec is the contract between internal services API developers and API developers consuming those services (whether inside or outside the company). With the platform, internal developers needed to build a service against the API’s specification, and consuming developers need to request against that specification in the same format. We worked with the team to enhance and add validations to the API spec. These enhancements help developers on both sides stay consistent, ensure that the API is flawless, catch and prevent errors, and ultimately, make their jobs easier. We also added artifact creation with tools like SDKs to make it easier for developers to adopt the spec and provide self-service capabilities.
To reach their goals, we helped the digital agriculture company as they shifted toward a testing-in-production paradigm. This shift means that testers and developers working with the API platform will embrace a contract-first cutting-edge approach. Contract-first testing was very different from their current approach, posing challenges for developers when testing their code. To improve the overall developer experience, we focused on building tools and validations to enable easy adoption and utilization of the platform and the new paradigm.
We also helped the organization enhance and build on its existing environment. They had a continuous integration continuous deployment (CI/CD) pipeline which we moved from Jenkins and Bitbucket to GitLab. This migration to GitLab was an organization-wide goal. Ours was one of the first of many teams to complete the migration, and we then helped another team also make the move to GitLab.
[HCDAgile] is surprisingly motivating for internal teams. People get way more productive and happy being involved in the process.
- Senior Director, Digital Agriculture Company
The Outcomes: New and Improved Developer Experience
The digital agriculture organization now has tools to help internal and external developers adjust to the significant paradigm shift in testing, ultimately improving their performance and overall experience. Developers have drastically changed how they do their work and now have structures in place to give them confidence in those changes.
Improved maintainability and collaboration
The modernized and enhanced CI/CD pipeline is more coherent and efficient. Cross-project interdependencies improve maintainability and enable effective collaboration on the shared API platform.
Accelerated development
We automated multiple OpenAPI Specification (OAS) validations upon merge requests to accelerate development and reduce costs by finding errors earlier. This also enabled developer self-service, improved confidence in proposing changes, reduced cognitive load and time spent manually validating by senior engineers and architects. These improvements include static linting of custom business and style rulesets, stub validation, and static analysis for breaking changes that could impact external partners.
Automatic reporting
We created automatically generated reports as part of the pipeline. API-to-service mapping enables easy communication of status, ownership, and roadmap for APIs. A human-readable list of linting rules provides easier access and visibility for the engineers.
Reduced barrier to entry
By creating an isolated, containerized (Docker) mock API, we reduced barrier to entry for API developers. The mock API also enabled early integration contract testing for planned APIs before they are actually implemented without incurring usage costs. Key features include random valid responses, full stubbed API responses, request validation, and security validation.
Reduced support costs
To help support adoption of the platform, we built multi-language authorization (OAuth 2.0) focused client SDKs. These SDKs supported multiple common grant types including robust examples to showcase usage for different workflows. We leveraged industry-standard open source authentication libraries to reduce support costs.
Increased collaboration and buy-in
The HCDAgile process helped develop a transparent, collaborative relationship that allowed the team to work quickly and effectively, building overall buy-in and collaboration. Ultimately, the solution is one that developers want to use and solves their biggest challenges.
