Demo Code with Examples for educational purpose
- Loose coupling
- Dynamic binding
- Utilization of (open) standards
- Deployment
- Shifts importance of Software Architects
- Higher invest in comparison to the usage of libraries
- Higher complexity in comparison to the usage of libraries
- Availability
- Security
- Versioing
- Performance
| Method | Semantics | Safe | Idempotent |
|---|---|---|---|
| OPTIONS | True | True | |
| HEAD | Read | True | True |
| GET | Read | True | True |
| PUT | Upsert | False | True |
| POST | Create | False | False |
| PATCH | Update | False | False |
| DELETE | Delete | False | True |
Remarks:
- Idempotence
- Cares about the state; doesn't require the response of a repeated operation to be identical
Further readings:
Most important
- Success
- Redirect
- Client Side Error
- Server Side Error (Fault)
Further readings:
- Virtual Hosting
- Request
- Connection Management
- Legacy (up to HTTP/1.1)
- General
- Legacy (up to HTTP/1.1)
- Protocol Upgrade
- Universal
- Request
- HTTP/2
- Request
- WebSockets
- General
- Request
- Response
- Universal
- Congestion Control
- Response
- Warning
- Response
- Discovery
- Response
- Content Modification
- Request
- Response
- Authentication
- Request
- Response
- Conditional Requests
- Strong Validation
- Response
- Request
- Weak Validation
- Response
- Request
- Strong Validation
- Content Negotiation
- Content Type
- Request
- Response
- Language
- Request
- Response
- Client
- User-Agent
- Request
- Client Hints
- Request
- User-Agent
- Content Type
- Files & Form-Data
- General
- Caching
- Compression
- Request
- Response
- Session
- Request
- Response
- Byte Range Request
- Request
- Response
- Embeddability in frames and iframes
- Response
- Cross Origin Resource Sharing (CORS)
- Content Security Policy (CSP)
- Response
- HTTP Strict Transport Security (HSTS)
- Response
- Strict-Transport-Security
- Response
- Tracking
- Request
- Response
- Cookies
- Request
- Response
- Information
- Response
In alphabetical order:
- Atom
application/atom+xml
- Form Data
- multipart/form-data
- HTML
text/html
- iCalendar
text/calendar
- JSON
application/json
- Protobuf
- not registered
- Currently in use
application/x-protobufapplication/vnd.google.protobuf
- Text
text/plain
- XML
application/xml
- YAML
- not registered
- Currently in use
text/x-yamlapplication/x-yamlapplication/yamlapplication/vnd.yaml
Further readings:
- Resouce oriented Web APIs
- Current development is domained by (pragmatic) REST
- RPC APIs
- Legacy applications still heavily utilize SOAP or EDI
- Current development is domained by gRPC
- Streaming APIs
- Query APIs
- Current development is domained by GraphQL
- Flat File APIs
Resources
Depends on Contraits
- Business Constraints e.g.
- Customer-related
- Business requirements
- Product requirements
- Complexity Constraints
- System complexity
- Evolution requirements
- Domain Constraints
- Domain-specific limitations
- Regulations
- Environments
- Cultural Constraints
- Conway's law
- Knownledge
- Human resources
- Peer-PRessure
- Trendiness
Resources
- Performance
- Network performance
- Network efficiency
- User-perceived
- Scalability
- Size complexity
- Simplicity
- Of the uniform interface
- User-perceived
- Task structure
- Unpredictability
- Algorithmic
- Chaotic
- Modifiability
- Evolvability
- Extensibility
- Customizability
- Configurability
- Reusability
- Visibility
- Monitoring
- Security
- Caching
- Portability
- Different environments
- Code with data
- Reliability
- Susceptibility to failure
- Ability to recover
- Deiscoverability
- Design-time
- Runtime
- Type-Safety
- Ease of development
- Server
- Client
- Cost effectivity
- Time to market
- Development cost
- Maintenance cost
- Cost of change
- Active community
- Tooling
- Server
- Client
- API management
- Developer experience
- Ecosystem maturity
- Resources
- Books
- Articles
- On-boarding tutorials
- Enterprise readyness
Resources
- Acronym for
Representational State Transfer - Dissertation of Roy Fielding (2000): Architectural Styles and the Design of Network-based Software Architectures
- RESTfulness of an architecture is defined by constraints
- Client-Server
- Stateless
- Cache
- Uniform Interface
- Identification of resources
- Manipulation of resources through representations
- Self-descriptive messages
- Interaction is stateless between requests
- Standard methods used
- Media types are used to indicate semantics and exchange information
- Responses explicitly indicate cacheability
- Hypermedia as the engine of application state
- Layered System
- Code-On-Demand (optional)
- See also REST APIs must be hypertext-driven
- Endpoint
- Hyperlink
- Intermediary
- Link Relation
- Resource
- Resource Collection
- Resource Identification
- Naming conventions
- Type conventions
- Representation of date and time (points, durations & intervals)
- API Discovery and Description
- Hyperlinking
- Locator representation
- Templating
- Relation semantics
- Locator representation
- Allowed actions
- Supporting actions that don't fit in the semantic corset of standard verbs
- Providing meta information
- Document structure
- Hyperlinking
- Retrieval of a single resource
- Partial resource retrieval
- Representation of relationships
- inclusion of related resources
- Manipulation of single resources
- Updating resources
- Partially updating resources
- Adding relationships
- Removing relationships
- Retrieval of resource collections
- Filtering
- Sorting
- Pagination
- Mainpulation of resource collections
- Adding/Upserting resources
- Generation of identifiers
- Client-side
- Server-side
- Polymorphy
- Type declaration
- Generation of identifiers
- Removing resources
- Tombstoning
- Trash Bin
- Adding/Upserting resources
- Searching
- Representation of error information
- Status Codes
- Document structure
- Change Management
- Undo
- Delta queries
- Events
- Batch requests
- Resilience
- Retrying requests
- Security
- Authentication
- Authorization
- API Lifecycle
- Compatibility
- Versioning
- Deprecation
- Compatibility
- Cachability
- Internationalisierung
- Asynchronicity
- Long running operations
- Initiation
- Status retrieval
- Cancellation
- Long running operations
- Availability
- Throttling
- Rate Limiting
- Consistency
- Optimistic concurrency control
- Conflict avoidance
- Conflict detection
- Conflict handling
- Transactions
- Optimistic concurrency control
- Multitenancy
- Measuring
- Monetization
- Developer experience
- Documentation
- Tooling
- Code on Demand
- Componentization via Services
- Organized around Business Capabilities
- Products not Projects
- Smart endpoints and dumb pipes
- Decentralized Governance
- Decentralized Data Management
- Infrastructure Automation
- Design for failure
- Evolutionary Design
In alphabetical order:
- API Blueprint
- Version 1A revision 9
- Licensed under MIT License
- Collection+JSON
- Current version released on February 2013
- Google API Design Guide
- Maintained by Google
- Current version released in February 2017
- HAL
- Acronym for Hypertext Application Language
- Current version release on September 2013
- Hydra
- Acronym for Hypermedia-Driven Web APIs
- Builds upon JSON-LD
- Current Version released in 2013
- Slides
- I/O Docs
- Current version released on July 2014
- JSON API
- Version 1.0 released on May 2015
- Microsoft REST API Guidelines
- Maintained by Microsoft
- Current Version released in October 2018, continuously improved
- OData
- Standardized by OASIS
- Version 4.0 released on February 2014
- Open API
- Also known as Swagger
- Version 3.0.2 released in 2018
- Favours usage of a descriptional document over discovery by hypermedia
- RAML
- Acronym for RESTful API Modeling Language
- Standardized by RAML Workgroup
- Version 1.0 released on August 2016
- Favours usage of a descriptional document over discovery by hypermedia
- Siren
- Version 0.6.2 released on April 2017
- Zalando RESTful API and Event Scheme Guidelines
- Maintained by Zalando
- Current version released on October 2016
Further readings:
- Design Guidelines
- Overview of RESTful API Description Languages
- On choosing a hypermedia type for your API
- RESTful API Designing guidelines — The best practices
- Ultimate Guide to 30+ API Documentation Solutions
In alphabetical order:
- CURIE
- Acronym for Compact URI
- Standardized by W3C
- Version 1.0 released on December 2010
- JSON-LD
- Acronym for JSON for Linked Documents
- Standardized by W3C
- Version 1.1 released on September 2018
- URI Template
- Standardized by IETF
- Current Version released in 2012
- WebHooks
- WebSockets
In alphabetical order:
- Compatibility
- REST & API Versioning
- Published on November 2017
- Your API versioning is wrong, which is why I decided to do it 3 different wrong ways
- Published on February 2014
- Evolving HTTP APIs
- Published on December 2012
- REST: Versprechen, Wirklichkeit & die Alternativen GraphQL, gRPC, ...
- When to Use What: REST, GraphQL, Webhooks, & gRPC
- REST vs. GraphQL: A Critical Review
- SOAP 1.2 has been standardized by W3C in April 2007
- SOAP is considered RPC while REST relies on manipulation of addressable ressources
- SOAP works without HTTP but is usually used on top, since communication via HTTP is usually enabled in a corporate security infrastructure
- Some HTTP Features are redundant to remove a dependencie to HTTP
- Tooling for HTTP cannot be used
- Only used verb is POST
- No HTTP Caching
- Informations in body
- No URL based filtering
- Only used verb is POST
- SOAP has a defined set of associated standards (WS-*), created by a few organizations