ReST API Design

Transcript

1. Design and development of Web APIs Milton Carranza Senior API Engineer @ MSD milton.carranza@merck.com https://msdit.cz/ 29.10.19
2. Agenda 29.10.19 THE BASIC PRINCIPLES BEHIND THE DESIGN. "BEST PRACTICES" FOR DESIGN AND DEVELOPMENT. API DOCUMENTATION API DESIGN API SECURITY API AUTOMATION
3. Web APIs REST API Design http://www.datascript.cz/en/courses/dev- test/rest-api-design/
4. API Styles of interest 29.10.19 https://speakerdeck.com/zdne/what-api-your-guide-to-api-styles Web APIs REST APIs (Architecture) So called REST APIs Query APIs GraphQL (Framework) SQL (Framework) Publish and Subscribe Kafka (Framework) WebSub (Recomendation) RPC APIs SOAP (Protocol) gRPC (Framework) Flat files
5. Trends over time 10/29/19
6. REST 29.10.19
7. What‘s REST? • Acronym for: Representational State Transfer • Architectural style to create web APIs
8. What‘s REST? • Architectural style to create web APIs • System where documents and other resources are identified by Uniform Resource Locators, linked by hypertext, and accessible over the Internet. • Who is the biggest enabler of this? • Who or what provides the rules to make this happen? 29.10.19
9. • Acronym for: Hyper Text Transfer Protocol
10. • Acronym for: Hyper Text Transfer Protocol • Protocol: set of rules • Transfer: Move from point A to point B • Text: Everything has a text representation… • Hyper-Text: ?
11. What‘s REST? • Architectural style to create web APIs • Acronym for: Active Pharmaceutical Ingredient
12. What‘s REST? • Architectural style to create web APIs • Acronym for: Application Programming Interface • Application: who is intended to consume • Programming: how is intened to be consumed • Interface: boundary between 2 entities • GUI • Graphical: how is intended to be consumed • User: who is inteded to consume • Interface: boundary between a computer and a user • Boundary between 2 entities / systems / modules / class / things • A contract.
13. What‘s REST? • Architectural style to create web APIs • set of constraints that imply a system with certain properties. • It’s the highest level of granularity. 29.10.19
14. REST constraints 29.10.19 Client-server architecture Statelessness Cacheability Layered system Uniform interface Code on demand (optional)
15. Client-server architecture REST Constraints
16. Statelessness REST constraints
17. Cacheability REST constraints
18. Layered system REST constraints
19. Code on demand REST constraints
20. REST API Design Best practices 29.10.19
21. Documenting APIs - API Design First Approach • API Specification • Contract • Several formats • API Blueprint (by Apiary) • Open API Specification – OAS (formerly know as Swagger) • Web Application Description Language – WADL • Restful Service Description Language – RSDL • Restful API Modeling Language – RAML • Benefits of using it • Developer Documentation • Mocks • Automated Testing • SDK Generation • Input Validation
22. Popular REST API Design guidelines Microsoft Google Zalando WSO2 Atlasian Agency for a digital Italy Cisco Heroku PayPal Adidas The White House
23. Common Patterns • Naming conventions • Use Plurals • Use Nouns • Don‘t use Verbs • There are always exceptions! • Good: • /orders, /vehicles, /positions • Bad • /create-order, /order • Exceptions • /v1, /search 29.10.19
24. Common Patterns • Use a Naming convention (only one and stick to it all over your APIs!) • camelCase • UpperCamelCase • snake_case • kebab-case • @ MSD we use kebab-case to name resources and headers, and camelCase to name query parameters and properties. • /my-products, /purchase-orders • /purchase-orders?dateFrom={date} 29.10.19
25. Common Patterns • HTTP Methods for actions • GET, POST, PUT, DELETE, OPTIONS, PATCH, … • HTTP Status Codes • 2XX, 3XX, 4XX, 5XX • Meaningful errors • 4XX, 5XX • Problem for APIs (Standard) • Content Negotiation • JSON by default • Enable Hypermedia • HAL • Siren 29.10.19
26. Common Patterns • Use common data types • Date and Time Format • ISO 8601 - 2019-10-30T09:19Z • Language Code Format • ISO 639 – en, es, zh • Country Code Format • ISO 3166-1 alpha-2 - CZ, SV, ES • Currency Format • ISO 4217 - CZK, USD, EUR 29.10.19
27. Common Patterns • Like scallability? • Use Pagination! • page & pageSize • offset & limit • dateFrom & dateTo • Long running tasks • Language Variants • Use Accept-Language headers • Use the ISO 639 J • Cache • Using Cache-Control header • Version your APIs • URLs, Headers 29.10.19
28. REST API - Security • Use TLS • 1 way TLS - minimum • 2 way TLS – good to have • Keep it Simple, Use a Standard! • Basic Authentication – not recommended • OAuth v2 • Other Mechanisms • API Keys 29.10.19
29. REST API - Security • Use common sense • Never expose information over the URLs - they may and will end up in the logs • Passwords • API Keys • Personal Identifyable Information • Session Tokens 29.10.19
30. REST API - Security • Rate Limiting • Throughput • Protect HTTP Methods • Input validation 29.10.19
31. API Automation • The precondition for any automation are flawless processes! • Design API Specification in a machine readable format • Resources, Methods, Path and Querystring Parameters, input and output Payloads, Authentication mechanisms, etc. 29.10.19
32. API Automation • Now we can automate several details: • Render Developer Documentation • Mocks server implementations for parallel API / Client development • Automated API Testing in your CI/CD pipeline • SDK Generation • Input Validation 29.10.19
33. Takeaways • Understand business problem first, and not privilege tech trends over business goals. • There are plenty of API Styles out there, make sure the one you choose is the right one for your use case • REST is not a silver bullet • Request/response communication model • Return a response as fast as possible • High number of transferred messages • Small payloads • Low latency 29.10.19
34. Takeaways • API as a reusable service • REST is an architecture, there‘s no agreement on how it should be implemented, it‘s about you choosing how you will keep consistency and stick to it all over your API ecosystem • Understand HTTP beyond that CRUD lifecycle, and don’t use something for which HTTP has already solved. 29.10.19
35. Web APIs REST API Design http://www.datascript.cz/en/courses/dev- test/rest-api-design/
36. Design and development of Web APIs Milton Carranza Senior API Engineer @ MSD milton.carranza@merck.com https://msdit.cz/ 29.10.19