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

SOLID (4/5) - Interface segregation principle

Interface segregation principle In the field of software engineering, the interface-segregation principle (ISP) states that no client should be forced to depend on methods it does not use. ISP splits interfaces that are very large into smaller and more specific ones so that clients will only have to know about the methods that are of interest to them. Such shrunken interfaces are also called role interfaces. ISP is intended to keep a system decoupled and thus easier to refactor, change, and redeploy. using   System ; namespace   interfacesegregation {      public   class   Document       {     }      public   interface   IMachine       {          void   Print ( Document   d );          void   Scan ( Document   d );     ...
Post a Comment
Read more

C# Extension Methods

 C# Extension Methods Extension methods      public   static   class   ExtensionMethods     {          public   static   Stopwatch   Measure ( this   Func < int >  f )         {              var   sw  =  new   Stopwatch ();              sw . Start ();              f ();              sw . Stop ();              return   sw ;         }          public   static   void   Save ( this   ISerializable   s...
Post a Comment
Read more

Configuring Ubuntu

Ubuntu Server Setting up a static IP // https://linuxhint.com/setup_static_ip_address_ubuntu/ // find the network interface name - eg: "enp9s0" ip a sudo nano /etc/netplan/00-installer-config.yaml network: version: 2 ethernets: ens33: addresses: [192.168.1.124/24] gateway4: 192.168.1.254 nameservers: addresses: [1.1.1.1, 8.8.8.8] Connecting to Server ssh root@server_ip_address Create a new user with admin rights adduser username usermod -aG sudo username sudo reboot Disabling Root Login and Limit login attempts(sshd_config) sudo vim /etc/ssh/sshd_config PermitRootLogin no LoginGraceTime 120 # allow only 1 login attempt per connection MaxAuthTries 1 sudo service sshd restart System update sudo apt-get update sudo apt-get upgrade Firewall sudo ufw status sudo ufw allow ssh sudo ufw allow http sudo ufw allow https sudo ufw enable sudo ufw status .NET Core wget https://packages.microsoft.com/config/ubuntu/20.10/packages-microsoft-prod.deb -O packages-...
Post a Comment
Read more