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
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.
• 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
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
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
& 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
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
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
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
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
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
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