move over intro: api lifecycle (#109)

philsturgeon · web-flow · commit e1d07398ca17 · 2025-07-06T07:11:22.000+08:00
* move over intro: api lifecycle

* removed some artifacts from markdown
diff --git a/src/1-introduction-to-apis/3-different-paradigms.adoc b/src/1-introduction-to-apis/3-different-paradigms.adoc
@@ -1,9 +1,8 @@
-[#theory-paradigms]
 = Understanding Different Paradigms
 
 If APIs are the interface for some sort of service, it should not come as a surprise that not all the interfaces in the world are going to have the same needs and requirements. Most of them are a case of "execute a command", "interact with data", or a combination of both.
 
-There are three distinct types of Web API which handles these common needs, and these different types are known as paradigms. To oversimplify things a bit, it’s reasonably fair to say that all APIs conform to one of these paradigms:
+There are three distinct types of Web API which handles these common needs, and these different types are known as paradigms. To oversimplify things a bit, it's reasonably fair to say that all APIs conform to one of these paradigms:
 
 - RPC (Remote Procedure Call)
 - REST (Representational State Transfer)
@@ -13,7 +12,7 @@ These paradigms are general approaches to building APIs, not a specific tool or
 
 *Implementations* are something you can actually download, install, and use to build an API, that conforms to whatever rules the implementors picked, from whichever paradigm (or paradigms) they were interested in at the time.
 
-*Specifications* (or standards, recommendations, etc.) are often drafted up by various working groups, to help implementations share functionality in the same way. An API and a client in different languages can work together perfectly if they’re all following the specification correctly. The difference between a standard and a specification is usually just down to who made it. When a working group like the IETF or W3C create something, it's a standard, but when Google knock something out on their own, it's a specification.
+*Specifications* (or standards, recommendations, etc.) are often drafted up by various working groups, to help implementations share functionality in the same way. An API and a client in different languages can work together perfectly if they're all following the specification correctly. The difference between a standard and a specification is usually just down to who made it. When a working group like the IETF or W3C create something, it's a standard, but when Google knock something out on their own, it's a specification.
 
 For example:
 
@@ -126,15 +125,15 @@ REST, however, presents you with the next available options:
 
 *Client:* Hi, I would like to speak to Dr Watson, is he there?
 
-*REST:* Doctor Watson is not currently in the office, he’ll be back tomorrow, but you have a few options. If it’s not urgent you could leave a message and I’ll get it to him tomorrow, or I can book you with another doctor, would you like to hear who is available today?
+*REST:* Doctor Watson is not currently in the office, he'll be back tomorrow, but you have a few options. If it's not urgent you could leave a message and I'll get it to him tomorrow, or I can book you with another doctor, would you like to hear who is available today?
 
 *Client:* Yes, please let me know who is there!
 
 *REST:* Doctors Smith and Jones, here are links to their profiles.
 
-*Client:* Ok, Doctor Jones looks like my sort of Doctor, I would like to see them, let’s make that appointment.
+*Client:* Ok, Doctor Jones looks like my sort of Doctor, I would like to see them, let's make that appointment.
 
-*REST:* Appointment created, here’s a link to the appointment details.
+*REST:* Appointment created, here's a link to the appointment details.
 
 REST provided all of the relevant information with the response, and the client was able to pick through the options to resolve the situation.
 
@@ -146,7 +145,7 @@ This book will get more in-depth on hypermedia controls later. There are a few o
 
 - REST must be stateless: not persisting sessions between requests
 - Responses should declare cacheablility: helps your API scale if clients respect the rules
-- REST focuses on uniformity: if you’re using HTTP you should utilize HTTP features whenever possible, instead of inventing conventions
+- REST focuses on uniformity: if you're using HTTP you should utilize HTTP features whenever possible, instead of inventing conventions
 
 These constraints of REST when applied to HTTP APIs can help the API last for decades, which is a whole lot more complex without these concepts. What does that mean? Well, REST is often described as a series of layers of abstraction on top of RPC, with all relevant instructions related to the handling of that message being baked into the message itself, to avoid having to tell a human about specific ways to handle things. As things change throughout the entire ecosystem, a well trained REST API and client should be able to handle those changes seamlessly, because the REST API is describing itself well and the client is listening. This loosens the coupling found in other paradigms, where a lot of that is baked into the client itself.
 
@@ -236,7 +235,7 @@ All of this has the advertised benefit of making GraphQL portable enough that it
 
 GraphQL has many fantastic features and benefits, which are all bundled in one package, with a nice marketing site. If you are trying to learn how to make calls to a GraphQL API, the http://graphql.org/learn/[Learn GraphQL] documentation will help, and their site has a bunch of other resources.
 
-Seeing as GraphQL was built by Facebook, who had previously built a REST__ish__ API, they’re familiar with various REST/HTTP API concepts. Many of those existing concepts were used as inspiration for GraphQL functionality, or carbon copied straight into GraphQL.
+Seeing as GraphQL was built by Facebook, who had previously built a REST__ish__ API, they're familiar with various REST/HTTP API concepts. Many of those existing concepts were used as inspiration for GraphQL functionality, or carbon copied straight into GraphQL.
 
 The main selling point of GraphQL is that it defaults to providing the very smallest response from an API, as you are requesting only the specific bits of data that you want, which minimizes the Content Download portion of the HTTP request.
 
diff --git a/src/1-introduction-to-apis/4-api-lifecycle.adoc b/src/1-introduction-to-apis/4-api-lifecycle.adoc
@@ -25,9 +25,9 @@ and could include people from marketing, sales, customer support, and more. The
 worst APIs are built in a vacuum, where the developers were told to build
 something and then left to their own devices.
 
-- "Marketing said we need to tack an API on." - "The CEO said we need to open up
-our data to third-party developers." - "A major partner wants to integrate our
-services into their platform."
+- "Marketing said we need to tack an API on." 
+- "The CEO said we need to open up our data to third-party developers."
+- "A major partner wants to integrate our services into their platform."
 
 If one one of these requests is being used as the entirety of the strategy input
 then the API will likely be very specific to that purpose. Maybe that's ok,
@@ -36,12 +36,13 @@ of potential stakeholders can help flesh out what the needs really are.
 
 Start by asking: 
 
-- Who are your target users? Internal teams, third-party developers, or both? -
-What are the business goals this API will help achieve? - What existing systems
-or data will the API interact with? - Which customers will be using this, and
-what are their needs? - If there is only one customer right now, can I find some
-other potential customers to talk to? - What sort of traffic can be expected?
-Will this be a few dozen users or millions worldwide?
+- Who are your target users? Internal teams, third-party developers, or both? 
+- What are the business goals this API will help achieve?
+- What existing systems or data will the API interact with?
+- Which customers will be using this, and
+what are their needs? 
+- If there is only one customer right now, can I find some other potential customers to talk to?
+- What sort of traffic can be expected? Will this be a few dozen users or millions worldwide?
 
 All of this can drastically shape the decisions made throughout the planning and
 development of the API, and could even suggest that you don't need a real-time
@@ -236,3 +237,28 @@ encourage adoption while generating revenue.
 
 With these steps, your API can evolve from an idea to a well-managed,
 developer-loved product that generates real value.
+
+== Summary
+
+Building an API is not just writing a bunch of code and hoping for the best, it's 
+an ongoing process that requires careful planning, design, testing, and management.
+This is a continuous cycle that adapts to changing requirements, technologies, and
+user needs over time.
+
+Some phases of the lifecycle will involve teams and stakeholders from other
+parts of the business, all of whom have different needs and expectations, so
+things can get a bit political. That's all very different skills required to
+more technical phases which are handled by developers, testers, and operations,
+but all are equally important to the success of the API.
+
+Of course people will try to skip a bunch of this and just get on with their one
+favourite step: Code. That's a bit like trying to build a house without a
+plan, or a recipe without ingredients. It might work, but it's not going to be
+pretty. You'll end up wasting a lot more time and money building useless things
+than you do building the right thing, but building the right thing requires a
+lot of work, and some decision makers "cut cost" by "reducing investment" like a
+UK Labour/Conservative government.
+
+We'll go through most of this in more detail in the following chapters, but
+hopefully this gives you a good overview of what to expect when building an API,
+and sets expectations for the challenge ahead.
diff --git a/src/1-introduction-to-apis/part.adoc b/src/1-introduction-to-apis/part.adoc
@@ -4,3 +4,4 @@
 include::1-history-of-apis.adoc[]
 include::2-apis-services-microservices.adoc[]
 include::3-different-paradigms.adoc[]
+include::4-api-lifecycle.adoc[]
diff --git a/src/4-api-design-first/2-the-perfect-workflow.adoc b/src/4-api-design-first/2-the-perfect-workflow.adoc
@@ -419,14 +419,6 @@ jobs:
           bundle exec rspec
 ----
 
-____
-For a more in depth example, see xref:_guides/openapi/design-first-rails.adoc[how to contract test in
-Rails], or see xref:_guides/openapi/design-first-laravel-php.adoc[how to do the same with
-Laravel PHP]. If you'd like to
-see a similar guide for your favorite language/framework please link:mailto:hello@bump.sh[get in
-touch].
-____
-
 If an API does not have an existing integration test suite this might seem like
 a bigger push, but an API without a test suite should absolutely add one.
 Working with a generic test suite and adding in some OpenAPI assertions can be a
@@ -439,10 +431,9 @@ To avoid having to train a tool to know what the expected contract is, why not
 use a tool which already knows what the latest OpenAPI is meant to be at
 anytime: Microcks again!
 
-Microcks handles xref:_guides/bump-sh-tutorials/testing-with-microcks.adoc[contract
-testing] as well as mock
-servers, and it does this by taking a URL to a server for comparison. This could
-be staging, pre-production, or even production if you're careful.
+Microcks handles contract testing as well as mock servers, and it does this by
+taking a URL to a server for comparison. This could be staging, pre-production,
+or even production if you're careful.
 
 It works by going through all the operations in the OpenAPI document, and uses
 the examples and schemas defined there to send a request that should work, to an
@@ -490,7 +481,7 @@ jobs:
           waitFor: '10sec'
 ----
 
-_Learn more about xref:_guides/bump-sh-tutorials/testing-with-microcks.adoc[contract testing with Microcks]._
+_Learn more about https://docs.bump.sh/guides/bump-sh-tutorials/testing-with-microcks/[contract testing with Microcks]._
 
 == Phase 3: Deploying Artifacts
 
@@ -584,7 +575,7 @@ workflow like this for clarity. Either way, whenever a change is made to the
 `main` branch the mock servers will be updated and instantly reflect the latest
 OpenAPI.
 
-_Learn more about xref:_guides/bump-sh-tutorials/mocking-with-microcks.adoc[API mocking with Microcks]._
+_Learn more about https://docs.bump.sh/guides/bump-sh-tutorials/mocking-with-microcks/[API mocking with Microcks]._
 
 === Publish SDKs
 
@@ -601,8 +592,8 @@ over HTTP directly.
 SDK generation tools have been around for a long time, but in the past the best
 offering was a cumbersome Java-based open-source tool where you generally had to
 develop your own templates. Modern tooling like
-xref:_guides/bump-sh-tutorials/generate-sdks-with-speakeasy.adoc[Speakeasy] and
-xref:_guides/bump-sh-tutorials/stainless-integration.adoc[Stainless] allow API
+https://www.speakeasy.com/[Speakeasy] and
+https://www.stainless.com/[Stainless] allow API
 providers to point to an OpenAPI document, and produce type-safe SDKs that your
 team will be proud of. These will handle tricky functionality like OAuth 2,
 retries, pagination, and even allow for adding custom code to the generated
@@ -650,8 +641,6 @@ or rudimentary code samples like using `fetch()` or other low-level HTTP code.
 
 image::images/bump-sdks.png[The Train Travel API documentation example on Bump.sh with a TypeScript SDK generated by Speakeasy showing in the documentation.]
 
-_Learn more about xref:_guides/bump-sh-tutorials/generate-sdks-with-speakeasy.adoc[SDK generation with Speakeasy]._
-
 === API Catalog
 
 Another key part of API governance is discoverability, which usually takes the
@@ -666,7 +655,12 @@ Alternatively, Hubs could be used to group APIs by team or department.
 
 image::images/bump-hubs.png[A list of APIs, descriptions, and last updated times, for a sample Hub on Bump.sh]
 
-_Learn more about xref:_guides/bump-sh-tutorials/api-discovery-using-bump-sh-hubs.adoc[API discovery with Bump.sh Hubs]._
+Making sure API catalogs are up to date and contain 100% of APIs can be tricky,
+but there are various ways to do it. One could be using an API Gateway that also
+happens to support API catalogs like [Kong
+Gateway](https://konghq.com/products/kong-gateway) and the [Service
+Catalog](https://konghq.com/products/kong-konnect/features/api-service-catalog).
+
 
 === Try it Now
 
