DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
What's in store for DevOps in 2023? Join us today at 11 am ET for the "DZone 2023 Preview: DevOps Edition!"
Last chance to join
  1. DZone
  2. Data Engineering
  3. Databases
  4. API Evangelist API Lifecycle Workshop on API Design

API Evangelist API Lifecycle Workshop on API Design

Let's take a quick look at an API lifecycle workshop on API design. Also, explore versioning and virtualization.

Kin Lane user avatar by
Kin Lane
·
Nov. 01, 18 · Opinion
Like (2)
Save
Tweet
Share
7.77K Views

Join the DZone community and get the full member experience.

Join For Free

I’ve been doing more workshops on the API lifecycle within enterprise groups lately. Allowing me to refine my materials on the ground within enterprise groups and further flesh out the building blocks I recommend to API groups to help them craft their own API strategy. One area of the API lifecycle I find more groups working on these days centers around a design-first approach to the API lifecycle.

While not many groups I work with achieved a design-first approach doing APIs, almost all of them I talk to express interest in making this a reality at least within some groups or projects. The appeal of being able to define, design, mock, and iterate upon an API contract before code gets written is very appealing to enterprise API groups, and I’m looking to help them think through this part of their API lifecycle and work towards making API design first a reality at their organization.

  • Definition (outline) — Using definitions as the center of the API design process, developing an OpenAPI contract for moving things through the design phase, iterating, evolving, and making sure the definitions drive the business goals behind each service.
  • Design (outline) — Considering the overall approach to design for all APIs, executing upon design patterns that are in use to consistently deliver services across teams. Leveraging a common set of patterns that can be used across services, beginning with REST, but also eventually allowing the leveraging of hypermedia, GraphQL, and other patterns when it comes to the delivery of services.
  • Versioning (outline) — Managing the definition of each API contract being defined as part of the API design stop for this area of the lifecycle, and having a coherent approach to laying out next steps.
  • Virtualization (outline) — Providing mocked, sandbox, and virtualized instances of APIs and other data for understanding what an API does, helping provide an instance of an API that reflects exactly how it should behave in a production environment.
  • Testing (outline) — Going beyond just testing, and making sure that a service is being tested at a granular level, using schema for validation, and making sure each service is doing exactly what it should, and nothing more.
  • Landing Page (outline) — Making sure that each individual service being designed has a landing page for acccessing its documentation and other elements during the design phase.
  • Documentation (outline) — Ensuring that there is always comprehensive, up to date, and if possible interactive API documentation available for all APIs being designed, allowing all stakeholders to easily understand what an API is going to accomplish.
  • Support (outline) — Ensuring there is support channels available for an API, and stakeholders know who to contact when providing feedback and answering questions in real, or near real time, pushing forward the design process.
  • Communication (outline) — Making sure there is a communication strategy for moving an API through the design phase, and making sure stakeholders are engaged as part of the process, with regular updates about what is happening.
  • Road Map (outline) — Providing a list of what is being worked on with each service being designed, and pushed forward, providing a common list for everyone involved to work from.
  • Discovery (outline) — Make sure all APIs are discoverable after they go through the design phase, ensuring each type of API definition is up to date, and catalogs are updated as part of the process.

I currently move my own APIs forward in this way using a variety of open source tooling, and GitHub. I’m working with some groups to do this in Stoplight.io, as well as Postman. I don’t think there is any “right way” to go API define and design first. I’m here to just educate teams about what is going on out there. What some of the services and tools that help enable an API design first reality, and talk through the technological, business, and political challenges are preventing a team, or entire enterprise group from becoming API design first.

Let me know if you need help thinking through the API design strategy where you work. I’ve been studying this area since it emerged as a discipline in 2012, led by API service providers like Apiary, but continue with other next-generation platforms like Stoplight.io, APIMATIC, and others. For me, API design is less about REST vs Hypermedia vs GraphQL, and more about the lifecycle, services, tooling, and API definitions you use. I’m happy to share my view of the API design landscape with your group, just let me know how I can help.

API Design

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • Kubernetes vs Docker: Differences Explained
  • How to Create a Real-Time Scalable Streaming App Using Apache NiFi, Apache Pulsar, and Apache Flink SQL
  • Top 10 Secure Coding Practices Every Developer Should Know
  • A Brief Overview of the Spring Cloud Framework

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: