MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST

[19th September 2020]: [Undisturbed REST: Achieving
Undisturbed REST (RAML)]
[Kuala Lumpur - Malaysia]

All contents © MuleSoft Inc. 2
• 1.Please keep yourself muted unless you have any question.
• 2.We encourage keeping your video for making our meetup
interactive.
• 3.You'll can also write down your questions in chat section.
• 4.Once you join write down your registered name in chat section so
we will have an attendance.
• 5.As this is our first online Meetup, we appreciate your valuable
feedback. Thanks.
Guidelines for Kuala Lumpur MuleSoft Meetup #1 [Virtual]

All contents © MuleSoft Inc.
Agenda
3
 Introductions
 Important Announcements and Latest Releases/News
 MuleSoft CONNECT:Now 2020
 MuleSoft Anypoint Platform Insiders
 Technical Session - Undisturbed REST: Achieving Undisturbed REST (RAML)
 Q/A and Networking time

Introductions
4
• About the organizers:
– Nitushree Jena
– Manish Yadav
• About the sponsors: MuleSoft , Billennium
A SHOW OF HANDS:
Who is new to this MeetUp?

Organizers
5

Speaker
6

Latest Release/News
Important Announcements

• Registration Link: https://connect.mulesoft.com/
• Blog Link
MuleSoft CONNECT:Now 2020

• MuleSoft Anypoint Platform Insiders
– As an Insider, you will be able to engage with our product leaders and designers to give
ongoing, real-time, insightful feedback.
– You will be able to see our latest designs, interact with features before release, and give
your impactful opinions through user studies, surveys, and pre-release interviews; across
the entire product development cycle, from idea generation to design to validation.
– You will have access to the online Hub where you can see all the studies that you have
been invited to with participation completely optional and to you and your availability.
– Join us and help drive the future of Anypoint Platform! Send in your nominations.
• Anypoint Studio 7.6.0 Release
Latest Releases/News

Take a stand !
10
• Nominate yourself for
the next meetup speaker
and suggest a topic as
well.

What’s next
11
• Share:
– Tweet your pictures with the hashtag #MuleMeetup #MuleSoftMeetup
– Invite your network to join: https://meetups.mulesoft.com/kuala-lumpur/
– Feedback:
– Contact your organizers Manish Yadav and Nitushree Jena to suggest topics
– Tweet your organizers at @NeetuJena, @Manish_Kyadav.
– Contact MuleSoft at meetup@mulesoft.com for ways to improve the program
– Your Feedback is Food for us
• Our next meetup:
– Date: TBD
– Location: Kuala Lumpur, Malaysia (Virtual)
– Topic: TBD

mike stowe
Achieving Undisturbed REST

Mike Stowe
• API Fanatic
• Open Source Contributor
• Author, Speaker, Consultant
• 15+ Years Hacking Professional Code
• DevRel and Pun Teller at RingCentral
https://mulesoft.com/restbook

IMPORTANT HANDLES
@mikegstowe @ringcentraldevs
This is me. This keeps me from
getting fired…

AN API IS
a way for two applications to
programmatically connect to each
other through a mutual interface.

WHY BUILD A API?

WEB APIs IN THE REAL WORLD
Today there are over 23,000 public APIs listed on
ProgrammableWeb, however the majority of web-
based APIs are internal APIs – being used for
system to system integrations, partner integrations,
and IoT devices such as smart phones, watches,
security systems, and other devices.
Fun note: in 2014 there were ~11,000 public APIs

Versioning is expensive…
for everyone.

I can definitely say that one
of the best investments we
ever made as a company was
in our API. It’s probably the
best marketing we’ve ever
done.”
“
-Ben Chestnut, Owner of MailChimp

I can definitely say our API
was a complete waste of
money...”
“
-Someone else with a very different experience

• Who is your API for?
• What type of API are you building?
• How are you going to maintain your API?
• How are you going to document your API?
• How are you going to let users interact with your API?
• How are you going to manage authentication, provisioning, throttling, and
developer security?
• How are you going to protect your servers against attacks, developer misuse,
etc?
• How are you going to manage support?
Have a Plan:

• Who are your end users?
- Current customers
- Business partners
- Third-party services
• What actions do they need access to?
- This means sitting down and talking to them!
• How can you involve them in the design process?
- Your users should be involved from Day One.
Who Will Be Using Your API?

• List out WHY you are making the API
– Saying that you’re exposing your data to users is not good enough-
explain HOW they will use it
• Explain how your API will interact with existing services
• List out the actions the API needs to be able to handle
– Users: add, edit, reset password, delete, etc…
– Messages: draft, send, retrieve, archive, etc…
• Do only what is NECESSARY
• DON’T get fancy.
What is the Purpose of Your API?

List Out What Your Users Need to be able to Do:

• Are you building a REST, partial REST, SOAP, RPC based, or
GraphQL API?
• Why are you building your API in that format?
• What does that mean for development?
• What does that mean for usability?
• What does that mean for longevity?
What Type of API Are You Building?

• Client-Server
• Stateless
• Cacheable
• Interface/ Uniform Contract
• Layered System
• Code on Demand (optional)
Do You Understand the REST
Constraints?

Most APIs are NOT
RESTful.

Versioning is a necessary
evil.

• Backwards incompatibilities
• Multiple Services to Maintain
• Multiple Systems to Support
• Creates confusion among developers
• Developer adoption is nearly impossible
Problems with Versioning

• Backwards incompatible platform changes
• Your API is no longer extendable
• Your spec is out dated (ie SOAP)
You Need to Version When:

• Added new endpoints
• Added additional data in response
• Changed technologies (java to ruby)
• Changed your application’s services (code)
But You Shouldn’t Version Just Because
You:

Your API should be designed to
avoid having to version it, not as
a “first draft” to be perfected
later.

“...people are fairly good at
short-term design, and
usually awful at long-term
design.”
“
-Dr. Roy Fielding

And a poorly designed API will cost you far
more in the long run, adding months to fix
what could have been prevented in weeks.
There are no shortcuts or quick fixes, you
can either build your API the right way to
begin with, or pay substantially for it in the
long-run.

Use Spec Driven Development
• Define your API before Coding
• Use Design Patterns/ Code Reuse
• Mock and get User Feedback
• Make Necessary Changes
• Start Coding – to the Spec
• DO NOT DEVIATE!

• Standardized – new developers can hit the ground running
• Consistent – uses design patterns and encourages code reuse
• Tested – used in production at companies large and small
• Concrete – becomes the foundation of your API
• Immutable – cannot be changed on the fly or by deleting code
• Persistent – allows evolution without breaking the API contract
Why Spec Driven Development?

Spec Driven Development means a two
stage, agile design and development
process. You should develop your spec
iteratively, incorporating agile user testing.
Then your development should be agile,
utilizing TDD – however - your API should be
static, driven by the spec with no deviation.

Hybrid Approach
Design Development
Continuous, fluid, changeable Static… No turns

The Agile Design Cycle
This creates a
continuous cycle of
agile user testing of our
design, ensuring we
meet costumers’ needs
and have a well
thought-out, carefully
designed and tested
API – before writing a
single line of code

• RAML
• IO Docs
• Swagger/ OAI
• API Blueprint
Choosing a Spec:

API Blueprint RAML Swagger / OAI
https://ringcentr.al/api-specs

• You can define your API in just a few lines of code
• You can see what it would look like as you go
• You can quickly prototype it for devs to try
• You can quickly make tweaks/ changes
• You can easily document your API
• You can let developers try your API online
• You can let developers interact with your and other APIs
• Generate SDKs/ client libraries for your API (REST United, APIMatic.io)
Using RAML You Can:

• You can use data models and design patterns
• You can reuse code (libraries, overlays, traits,
resourceTypes)
More Importantly…
resourceTypes:
- collection:
description: Collection of available <<resourcePathName>> in Jukebox.
get:
description: Get a list of <<resourcePathName>>.
responses:
200:
body:
application/json:
example: |
<<exampleCollection>>

What Does RAML Look Like?
#%RAML 1.0
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
/playlists:
get:
responses:
200:
body:
application/json:
example: |
{
“playlistID” : 1,
“playlistName” : “My Awesome Playlist”,
“genre” : “top40”,
“songs” : 40
}

The RAML API Designer

Remember, your spec is not a one-and-
done, rather it is the blueprint for your
API. Anytime you do something to your
API you should be modifying the spec
and going through user testing before
writing code. You should never have
code that does something not defined
by your spec.

Developers do not want to
code against an API that is
just going to be thrown
away or might change the
next day.”
“
-Gareth Jones, Principle API Architect, Microsoft OneNote

getpostman.com

apinotebook.com

Remember, hands on user feedback is
CRUCIAL to the success of your API,
ensuring developers can not only use
your API, but that it meets their needs.

Once your spec is finalized, you can now
use the prototype to enable parallel
development, significantly reducing
time to market.

Use Nouns.

Plural == Collection.

Use:
/users
Not:
/createUser
/getUser
/deleteUser
Use:
/addresses
Not:
/address
/user/address
/getAddress

Remember CRUD.

Create (POST)
Read (GET)
Update (PUT/ PATCH)
Delete (DELETE)

Use Accept/
Content-Type Headers.

Using headers gives you flexibility to support multiple
types of formats from the same resource without
worrying about breaking backwards compatibility.
Most common:
• application/json - wider language support
• application/xml
Use Accept/ Content-Type Headers

Use Response
Codes.

200 – OK
201 – Created
304 – Not modified
400 – Bad Request
401 – Not Authorized
403 – Forbidden
404 – Page/ Resource Not Found
405 – Method Not Allowed
415 – Unsupported Media Type
500 – Internal Server Error

418 – I’m a Teapot…
420 – Enhance Your Calm
501 –
Or if you’re feeling super creative…

Use Descriptive
Error Messages.

{
'error' {
'code' : 'e3526',
'message' : 'Missing UserID',
'description' : 'A UserID is required to edit a user.',
'link' : 'http://docs.mysite.com/errors/e3526/'
}
}
The more information you provide, the easier it
will be for developers to integrate your API
without contacting Support.

• vnd.error
• Google Errors
• JSON API
Common Descriptive Error Formats

Don’t forget Cache.

Wait!?
What is Hypermedia.
HATEOAS

Hypercard, originally released in 1987
(Hypercard clone HyperStudio shown)

Oregon Trail, originally released in 1971

The internet, with the first .COM (symbolics.com) being
registered in 1985

CPHL
{
"data" : {
"user" : {
"fname" : "Mike",
"lname" : "Stowe",
"_links" : {
"edit" : {
"href" : "/api/user/id/1",
"methods" : ["put", "patch"]
},
"messages": {
"href" : "/api/message/id/1/lname/last”,
"methods" : ["post"]
}
}
}
}
}

Hypermedia is the catalyst that removes
business logic from the client, allowing for
the free evolution of the API (or server).

{
"firstName" : "Mike",
"lastName" : "Stowe",
"_links" : {
"message" : {
"href" : "/api/messages/?user=1",
}
}
}

{
"firstName" : "Mike",
"lastName" : "Stowe",
"_links" : {
"message" : {
"href" : "/api/messages/?user=1&tkn=123",
}
}
}

• HAL
• JSON-LD
• JSON API
• Collection+JSON
• Siren
• CPHL*
Most Popular Hypertext Link Specs

HAL/CPHL"_links" : {
"edit" : {
"href" : "/api/user/id/1",
},
"messages": {
"href" : "/api/message/id/1/lname/last”,
"methods" : ["post"]
}
}

Documentatio
n
& API Sharing
12

• A clear explanation of what the method/resource does
• Call outs that share important information with developers, including warnings and errors
• A sample call with the correlating media type body
• A list of parameters used on this resource/method, as well as their types, special
formatting, rules and whether or not they are required
• A sample response, including media type body
• Code examples for multiple languages including all necessary code (e.g. Curl with PHP,
as well as examples for Java, .Net, Ruby, etc.)
Creating GREAT Documentation

• SDK examples (if SDKs are provided) showing how to access the
resource/method utilizing the SDK for their language
• Interactive experiences to try/test API calls (API Console, API Notebook)
• Frequently asked questions/scenarios with code examples
• Links to additional resources (other examples, blogs, etc.)
• A comments section where users can share/discuss code
• Other support resources (forums, contact forms, etc.)
Creating GREAT Documentation

Be sure to keep your documentation up to
date and simple enough for developers to
quickly find and implement solutions to
even the most complex problems.
Poor documentation has been the
death of many an API.

5 Minute – Always up to date documentation
(raml.org/projects)

It only takes ONE little thing to significantly
reduce your API’s life span. Every action
you make on your API must be carefully
thought out and tested BEFORE being
pushed to production.

Remember...

Building an API is easy.

Designing an API
is hard.

Get the
Workshop
https://undisturbedrest.com
Tweet me
@mikegstowe

Networking time
Introduce yourself to your neighbors!

See you next time
Please send topic suggestions to the organizer

MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST

MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST

Recommended

Recommended

More Related Content

What's hot

What's hot (19)

Similar to MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST

Similar to MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST (20)

More from Manish Kumar Yadav

More from Manish Kumar Yadav (9)

Recently uploaded

Recently uploaded (20)

MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST