API Design
1. Introduction
What is an API
Application Programming Interface
- A software interface, a building block that works behind the scenes to connect different applications and
- systems so they can share information.
- Entry points into your organization's capabilities that can be accessed through different channels such as browsers, mobile apps, social networks, and IoT devices.
- Are digital enablers
Digital feedback loop
Business Goals -> Digital Reach -> Business Results -> Data-driven Insigths
Benefits and Value of APIs
- New revenew - monetized access to data and services
- Reach and retention - reach captive audiences where they spend their time
- Faster partnerships - partners can onboard in record time
- Mobile ad omnichannel - consistent digital experience across all channels
- Interaction analytics - digital feed loop allows real-tims analysis of user behaviour
- Outsourced innovation - leads to unanticipated innovation from third party developers
- Self-service integration - rapid integration of disparate business capabilities and assembly of new products
- Organizational agility - Adoption of an "API First" engineering philosophy along with a microservices achitecture maximizes delivery speed, system stability and scalability
2. The API360 Model
Key components
- Alignment and usefulness
- strategy
- business goals
- funded projects
- future value
- unmet needs
- disruptors
- business value
- deliverables
- API roadmap and project cross reference
- Organizational model
- API Business model and business cases
- Engagement and usability
- stategy
- consumers
- developers
- attract and retain
- consumer needs
- developer experience
- tools
- deliverables
- developer program
- API and DX design principles
- API consumer toolkits
- Hands-on education programs
- Scalability and evolvability
- strategy
- factors
- runtime
- version
- tecnhology trends
- constraints
- leverage
- deliverables
- API architecture guidelines
- full API lifecycle methodology
- technology roadmaps
- intensive skills training
- Manageability and security
- strategy
- operational metrics
- business metrics
- increase business agility
- control access
- protect privacy
- threats
- deliverables
- API analytics and monitoring
- API identity and security model
- API infrastructure and operations
- API management platform
3. API Styles
Standards are usually formal documents that establish uniform engineering or technical criteria, methods, processes, and practices.
Styles refer to abstract plans or conventions for the construction of an object or a system, such as architectural blueprints, engineering drawings or business processes.
Tunel Style (SOAP - Simple Object Access Protocol)
- Exposes an RPC-like interface and provides an interface descriptor binding
- Uses an XML-centric message format
- Uses HTTP as a transport protocol for a higher application-level protocol
Advantages
- RPC
- tooling
- governace model
Limitations
- stack dependencies
- XML-centric
- Ingores HTTP features
URI Style (CRUD)
- Exposes an object or resource-centric API
- URIs and query parameters are used to identify and filter objects
- CRUD (Create Read Update Delete) operations are mapped to HTTP methods
Advantages
- HTTP path & query is "well known"
- Object "tooling" is good
- "hacking" is relatively easy
Limitations
- URI modeling is not a standard
- HTTP method set is very small
- May became "chatty"
Hypermedia Style (REST - Representational State Transfer)
- Exposes a task-based interface, often incorporating a workflow or state machine
- Uses media to describe link semantics, template-based input and message structures
- Provides its own URIs
Advantages
- Media Types can be customized
- Growing body of guidance
- Favors services that will last many years
Limitations
- Poor "tooling" (MSFT WebAPI)
- Assumed to be "too hard"
- Limited use in publics APIs (AWS AppStream API)
Event-driven/Reactive Style
- Emphasis on event notifications
- Asynchronous communication, "Reactive"
- Emerging style
- HTTP-based technologies: WebHooks, WebSockets
- Non-HTTP technologies: Apache Kafka, AMQP
- Popular with Domain-Drive Design (DDD), Command Query Responsability Segregation (CQRS), Microservices
GraphQL
- Query language for APIs
- Originated at Facebook
- Intended for flexibility of arguments
gRPC
- HTTP2-based protocol
- Originated at Google
- Intended for high scale communication
4. Designing APIs for Developers
Design: Funcionality, Usability, Experience
Functionality
- Will the PI aloow me to access the data I need
- Will it be running when I need it
- Will I be able to connect to the system I want
Usability
- How long will it take for me to get started
- How difficult will it be for me to understand what is happening
- How easily will I be able to fix mistakes
Experience
- How does the API make me feel (DX)
- The sum of interactions between the developer and the API designer
- The emotive impact of API usage on the developer
Developer experience DX
Troubleshooting
- Clear error messages
- Defect tracking
- Documentation
- Time to fix
Change management
- API versioning
- Release history
- Backward compatibility
- Upgrade or migration process
Education
- Documentation
- Annotations, sample code, scripts and SKDs
- Demonstrations
- Developer community engagement
Visibility
- Log and usage access
- Transaction tracing
- Intuitive search funtion
Trust
- Application stability
- Honest communication
- Security
5. Overcoming API Design Obstacles
API challenges
- Cost
- Scalability
- Security
Design Obstacles
- The perspective obstacle
- Bias
- Assumptions
- Resourses
6. Architecturing your API
API architecture: The process of developing a software interace that exposes backend data and application functionality for use in new applications.
Qualities
- Security
- Usability
- Reliability
- Testability
- Scalability
Layers
- Client Application
- Security
- Caching
- Representation
- Orchestration
- API/Resource
Design approach
- Determine goals
- Identify users
- Design interface
- Evaluate
- Implement
Interface design feedback loop
- Use sketching and prototyping to find the best design
- Difficult to change API after it is released
- Get feedback early in design process
- Continue with user testing
- Always refer back to design while in implementation
7. API Change Management
Change management
- Versioning APIs and communicating what is new and what the risks and considerations ar for upgrading
- Providing a clear release history, to easily track new and deprecated features and bugs, no matter which version a user is running
- Supporting backword compatibility
- When choosing to deprecate, making the upgrade or migration process as painless as possible
Postel's Law: Be conservative in what you send, be liberal in what you accept.
Extending the interface
- Never take anything away
- Never change the meaning of existing things
- Make all new changes optional
Fork
- Create a new version
- Be clear about the new version so there is no confusion
- Make forks very easy to identify
- Make it easy to build
- Make it easy to test
- Support both versions in parallel
- Make it as hard as possible for the user to mix the versions up
Comments
Post a Comment