So let's start talking about how the open API specification can
actually help you in your design. So designing is important because designing
an API even before anything is started actually forces you to think about a
couple of things and one is you know it makes it's very important to start
thinking about what is your business's taxonomy. It's not a technology thing,
remember like you're not moving away from a data-driven approach to a more
consumer friendly consumer focus business friendly approach so we need to
understand what is the organization's business taxonomy. What do I mean by this?
Well let's take for example, if say for example you are a payment
provider like say PayPal or Braintree but in that case your business taxonomy
is looking at all the different bounds of your various services
within your technological infrastructure that tied to a specific business. So you
will have say for example a payments and invoicing feature service, you will have
a client ID service, you will have a credit card service. All of these
different things are the bounds of your business taxonomy. And so now when you
start thinking about well okay this is my business taxonomy now I have to
create a new API instead of going in and developing it, further designing the
interface will actually force you to think, "Well, what are the different resources
which I'm going to be exposing that touches on different aspects of my
business taxonomy?" And then you can actually start, you will
start to understand the intricate ways in which the relationships that form
between these different systems. So once you have identified this you actually
start to think about, how can this API bring tangible outcomes to my
internal processes? What is the tangible outcome it provides to business? And
finally what is the tangible outcome it provides to customer? Designing the
interface actually forces you to do all these different things and
that's a great thing to do because at the end of the day remember your APIs
drive your internal and external strategy. So this is an example of a
design right it's this is an open API 2.0 or Swagger 2.0
and over here notice that it's again if this is the design API and it's there's
no code involved in this it actually just talks about what is the API
description, what is there, what is the high-level information you can provide
for this API, what are the various requests associated with it, and finally
what is the responses for every single app for the operation over here. Right so
it's a simple design. Of course this is just a simple API example
but as your API becomes more complex as you add more resources designing the
interface becomes a little more challenging. But also these long-term
positive ramifications the other big advantage of designing is that it keeps
all the internal stakeholders aligned right so if say for example the green
bar you see on the screen is the design of the API or the restful interface as
we want to call it you will actually see that this actually keeps all of the
internal stakeholders from the testers and developers and the architects and
technical writers all of them aligned and in sync on what the API does because
remember the contract defines what the API is. It talks about the requests the
responses for every single resource and so there's no second question, there's no
big questions in people's minds, they know what this API does so it keeps all of
them in sync and helps actually communicate, keep all of them have and
helps actually communicate the value of the pair to the stakeholders as well. So
a real life example is PayPal. PayPal actually has a system in place
internally, where they actually go to a stringent
review process when whenever you're building a new API they first start with
you know anytime someone wants to create a new API they go to an alignment
exercise where they look at the business taxonomy and they determine where the
API fits into that, then all the different internal stakeholders sign off
on that, after which they go about designing the API first. So they designed
the API interface and only then, once you've again verified the design with
all the technology stage stakeholders, only then you actually develop and
deploy it and this is something which is used by PayPal.