Weitere ähnliche Inhalte Ähnlich wie MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST (20) Mehr von Manish Kumar Yadav (9) Kürzlich hochgeladen (20) MuleSoft Meetup slides_kualalumpur_19thSept_Undisturbed REST: Achieving Undisturbed REST2. 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]
3. 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
4. All contents © MuleSoft Inc.
Introductions
4
• About the organizers:
– Nitushree Jena
– Manish Yadav
• About the sponsors: MuleSoft , Billennium
A SHOW OF HANDS:
Who is new to this MeetUp?
8. All contents © MuleSoft Inc. 8
• Registration Link: https://connect.mulesoft.com/
• Blog Link
MuleSoft CONNECT:Now 2020
9. All contents © MuleSoft Inc. 9
• 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
10. All contents © MuleSoft Inc.
Take a stand !
10
• Nominate yourself for
the next meetup speaker
and suggest a topic as
well.
11. All contents © MuleSoft Inc.
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
13. All contents © MuleSoft Inc.
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
16. All contents © MuleSoft Inc.
IMPORTANT HANDLES
@mikegstowe @ringcentraldevs
This is me. This keeps me from
getting fired…
18. All contents © MuleSoft Inc.
AN API IS
a way for two applications to
programmatically connect to each
other through a mutual interface.
22. All contents © MuleSoft Inc.
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
24. All contents © MuleSoft Inc.
Versioning is expensive…
for everyone.
26. All contents © MuleSoft Inc.
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
27. All contents © MuleSoft Inc.
I can definitely say our API
was a complete waste of
money...”
“
-Someone else with a very different experience
28. All contents © MuleSoft Inc.
• 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:
29. All contents © MuleSoft Inc.
• 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?
30. All contents © MuleSoft Inc.
• 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?
31. All contents © MuleSoft Inc.
List Out What Your Users Need to be able to Do:
32. All contents © MuleSoft Inc.
• 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?
34. All contents © MuleSoft Inc.
• Client-Server
• Stateless
• Cacheable
• Interface/ Uniform Contract
• Layered System
• Code on Demand (optional)
Do You Understand the REST
Constraints?
38. All contents © MuleSoft Inc.
• Backwards incompatibilities
• Multiple Services to Maintain
• Multiple Systems to Support
• Creates confusion among developers
• Developer adoption is nearly impossible
Problems with Versioning
39. All contents © MuleSoft Inc.
• Backwards incompatible platform changes
• Your API is no longer extendable
• Your spec is out dated (ie SOAP)
You Need to Version When:
40. All contents © MuleSoft Inc.
• 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:
41. All contents © MuleSoft Inc.
Your API should be designed to
avoid having to version it, not as
a “first draft” to be perfected
later.
42. All contents © MuleSoft Inc.
“...people are fairly good at
short-term design, and
usually awful at long-term
design.”
“
-Dr. Roy Fielding
43. All contents © MuleSoft Inc.
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.
44. All contents © MuleSoft Inc.
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!
45. All contents © MuleSoft Inc.
• 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?
46. All contents © MuleSoft Inc.
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.
47. All contents © MuleSoft Inc.
Hybrid Approach
Design Development
Continuous, fluid, changeable Static… No turns
48. All contents © MuleSoft Inc.
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
49. All contents © MuleSoft Inc.
• RAML
• IO Docs
• Swagger/ OAI
• API Blueprint
Choosing a Spec:
50. All contents © MuleSoft Inc.
API Blueprint RAML Swagger / OAI
https://ringcentr.al/api-specs
51. All contents © MuleSoft Inc.
• 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:
52. All contents © MuleSoft Inc.
• 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>>
53. All contents © MuleSoft Inc.
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
}
56. All contents © MuleSoft Inc.
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.
61. All contents © MuleSoft Inc.
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
64. All contents © MuleSoft Inc.
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.
65. All contents © MuleSoft Inc.
Once your spec is finalized, you can now
use the prototype to enable parallel
development, significantly reducing
time to market.
69. All contents © MuleSoft Inc.
Use:
/users
Not:
/createUser
/getUser
/deleteUser
Use:
/addresses
Not:
/address
/user/address
/getAddress
72. All contents © MuleSoft Inc.
Create (POST)
Read (GET)
Update (PUT/ PATCH)
Delete (DELETE)
75. All contents © MuleSoft Inc.
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
77. All contents © MuleSoft Inc.
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
78. All contents © MuleSoft Inc.
418 – I’m a Teapot…
420 – Enhance Your Calm
501 –
Or if you’re feeling super creative…
80. All contents © MuleSoft Inc.
{
'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.
81. All contents © MuleSoft Inc.
• vnd.error
• Google Errors
• JSON API
Common Descriptive Error Formats
90. All contents © MuleSoft Inc.
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"]
}
}
}
}
}
92. All contents © MuleSoft Inc.
Hypermedia is the catalyst that removes
business logic from the client, allowing for
the free evolution of the API (or server).
93. All contents © MuleSoft Inc.
{
"firstName" : "Mike",
"lastName" : "Stowe",
"_links" : {
"message" : {
"href" : "/api/messages/?user=1",
"methods" : ["put", "patch"]
}
}
}
94. All contents © MuleSoft Inc.
{
"firstName" : "Mike",
"lastName" : "Stowe",
"_links" : {
"message" : {
"href" : "/api/messages/?user=1&tkn=123",
"methods" : ["put", "patch"]
}
}
}
95. All contents © MuleSoft Inc.
• HAL
• JSON-LD
• JSON API
• Collection+JSON
• Siren
• CPHL*
Most Popular Hypertext Link Specs
96. All contents © MuleSoft Inc.
HAL/CPHL"_links" : {
"edit" : {
"href" : "/api/user/id/1",
"methods" : ["put", "patch"]
},
"messages": {
"href" : "/api/message/id/1/lname/last”,
"methods" : ["post"]
}
}
98. All contents © MuleSoft Inc.
• 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
99. All contents © MuleSoft Inc.
• 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
100. All contents © MuleSoft Inc.
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.
101. 5 Minute – Always up to date documentation
(raml.org/projects)
103. All contents © MuleSoft Inc.
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.
110. See you next time
Please send topic suggestions to the organizer