Skip to main content

API Designer

API Design

source: https://apiacademy.co/category/api-tutorials/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

Labels:

Comments

Post a Comment

Popular posts from this blog

XML Webservice (ASMX) - SOAP Request and Response Invocation logging

You are an integration developer. Eventualy you came into the state where there is nothing else you can debug, and you have to check which SOAP request it is built on the request, and which SOAP response you are getting from the server. C# XML Webservice (ASMX) - SOAP Request and Response Invocation logging In the legaccy .NET framework System.Web.Services , this means using soapExtensions to help you intersept the interaction with the webservice. This is done like so:  public class TraceExtension : SoapExtension     {         Stream oldStream;         Stream newStream;         string filename;         // Save the Stream representing the SOAP request or SOAP response into          // a local memory buffer.          public override Stream ChainStream(Stream stream)         {           ...
Post a Comment
Read more

Abstract Factory Pattern

Abstract Factory Pattern  Gamma Categorization: Creational Design Patten Summary: When the object construction is complicated, needing multiple arguments, we should create a separate function (Factory Method) or class (Factory), which is responsible for the creation of the all object. Problem examples Suport of multiple databases Multiple data sources: Serial port, ethernet port, device driver Diferent report types Solution Abstract class Generalized interface A Factory creates instances of the concrete classes Sample Code The abstract factory public   interface   IPhotoFactory {      IAnaloguePhoto   CreateAnaloguePhoto ();      IDigitalPhoto   CreateDigitalPhoto (); } The abstract products public   interface   IAnaloguePhoto {      string   GetName (); } public   interface   IDigitalPhoto {      ...
Post a Comment
Read more

SOLID (1/5) - Single Resposibility Principle

 SOLID (1/5) - Single Resposibility Principle The single-responsibility principle (SRP) is a computer-programming principle that states that every class in a computer program should have responsibility over a single part of that program's functionality, which it should encapsulate. All of that module, class or function's services should be narrowly aligned with that responsibility. In the following example we have a TodoList class which only handles it's own functionality logic, and then we have a Persistance class which handles the saving logic, hence keeping the concerns separeted. using   System ; using   System . Collections . Generic ; namespace   Journal {      public   class   TodoList     {          private   readonly   List < string >  _entries  =  new   List < string >();          private...
Post a Comment
Read more