Upgrade to Pro — share decks privately, control downloads, hide ads and more …

ReST API Design

ReST API Design

Milton Carranza

October 30, 2019
Tweet

Other Decks in Technology

Transcript

  1. Agenda 29.10.19 THE BASIC PRINCIPLES BEHIND THE DESIGN. "BEST PRACTICES"

    FOR DESIGN AND DEVELOPMENT. API DOCUMENTATION API DESIGN API SECURITY API AUTOMATION
  2. 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
  3. 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
  4. • 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: ?
  5. What‘s REST? • Architectural style to create web APIs •

    Acronym for: Active Pharmaceutical Ingredient
  6. 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.
  7. 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
  8. 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
  9. Popular REST API Design guidelines Microsoft Google Zalando WSO2 Atlasian

    Agency for a digital Italy Cisco Heroku PayPal Adidas The White House
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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
  17. REST API - Security • Rate Limiting • Throughput •

    Protect HTTP Methods • Input validation 29.10.19
  18. 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
  19. 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
  20. 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
  21. 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