Application Programming Interfaces (APIs) now serve as the glue connecting software applications and services across the web. Global API traffic currently exceeds 70 million requests per second according to industry monitors. This deluge of API-driven data underlies the apps we use daily to hail rides, post social media updates, and binge our favorite shows.
And yet, not all APIs share the same architecture. Like snowflakes, each one adopts subtly different technical styles and access policies tailored to meet specific needs.
This guide serves as an API field guide, allowing readers to visually identify different species of APIs and learn their ideal habitats. By understanding API distinctions, builders can make informed decisions, avoid common pitfalls, and most effectively leverage different API capabilities.
We will explore:
- API access models — Who can use it?
- API architectures — How does it work under the hood?
- Real-world examples of API species
- How to match API traits to use cases
So without further ado, let the API safari begin!
Mapping API Access Models
APIs employ different access policies depending on intended consumers:
Let‘s visually map out these different API access models in the landscape.
Public APIs: Open Data Access
Public APIs place resources openly out in the wilderness available for all developer species to freely access. Instead of constantly re-collecting basic data themselves, developers can tap public APIs to embed existing capabilities in their own apps.
For example the Twitter API allows developers to easily integrate social capabilities like profiles, tweets, and notifications. Public transportation apps like CityMapper build upon Google Maps location APIs. And sites providing weather use open data APIs from providers like AccuWeather and DarkSky.
Adoption: Public API traffic exceeds 50 billion daily requests.
Pros
- Encourage innovation by simplifying access
- Allow developers to focus on creating specialized capabilities
- Enable startups and indie developers to leverage powerful services
Cons
- Can expose providers to risk if APIs lack proper security controls
- Subject to usage limits, licensing restrictions or fees
- Rely on provider API remaining available long-term
Public APIs serve as a thriving hub and melting pot enabling software ecosystems to form across industries.
Internal APIs: Secured company data
Behind company walls Internal APIs provide private access to sensitive business data and logic. These internal-facing APIs allow employees and systems to share information within the company boundary.
For example, banks use internal APIs to allow various departments like ATMs, mobile apps, financial advisors etc to tap into core banking capabilities. Rideshare providers enable internal trip data APIs for use across accounting, analytics, and customer service portals.
Adoption: Nearly 80% of organizations leverage internal APIs according to surveys.
Pros
- Improves security by limiting external exposure
- Speed development by reusing existing services
- Promote internal alignment around canonical data sources
Cons
- Adds overhead of internal API development and governance
- Departmental politics can impede adoption
- Lack of internal skills to use properly
Well-managed internal API programs serve as the circulatory system enabling information exchange within a company.
Partner APIs: Sharing capabilities
Partner APIs provide external business partners limited access to internal capabilities. Retailers allow third-party merchants to integrate using Seller APIs. Social platforms enable posting from partner apps via APIs. And Banking APIs give financial tech apps controlled access to transaction data.
Adoption: The Partner API market projected to reach nearly $300 billion by 2026.
Pros
- Expand services by allowing partners to integrate
- Foster partnership opportunities
- Maintain control over external data access
Cons
- Adds complexity around security, availability and access
- Partner changes can break integrations
- Requires managing external partner relationships
Exposing information safely to partners allows organizations to focus on their specialized capabilities while enabling collaborative growth.
Composite APIs: API aggregators
Composite APIs consolidate access to multiple internal APIs behind a simplified facade API. Instead of separate payments, shipping, inventory, analytics APIs, an ecommerce provider could offer a unified Checkout API.
Adoption: Nearly 50% of organizations employ API aggregation approaches.
Pros
- Simplifies API portfolio
- Reduce need to orchestrate discrete APIs
- Optimize APIs for particular use cases
Cons
- Increases complexity developing and maintaining
- Issues cascade across aggregated capabilities
Composite APIs serve as a virtual Swiss Army knife consolidating access to a handy set of capabilities through a single interface.
This visual map covers the major API access models. Next let‘s explore common API architectural styles.
Classifying API Architectures
Beyond simply who uses them, APIs also utilize varied underlying technical architectures dictating how they operate. Let‘s visually depict some of the most widespread API archetypes.
REST APIs: Scalable web infrastructure
REST (Representational State Transfer) leverages core web technologies using:
- HTTP methods to manipulate resources
- URIs to identify resource locations
- Responses indicating outcomes
- Formats like JSON and XML to represent data
This simple yet powerful model allows the same API to support web sites, mobile apps, IoT devices and more.
Adoption: Over 80% of public API traffic utilizes REST.
Pros
- Broadly adopted across web infrastructure
- Leverages existing skills and tools
- Horizontally scalable to handle load
Cons
- No standards beyond HTTP so consistency challenges
- Can fetch too much or too little data
- Not ideal for complex processes
For widely accessible APIs, REST provides a scalable lingua franca.
SOAP APIs: Enterprise Integration
SOAP (Simple Object Access Protocol) excels in enterprise integration scenarios requiring:
- XML documents for requests and responses
- XML Schema for contract definitions
- WS-Security and transactions
- Tooling for interface documentation
Adoption: 77% of internally-facing integration APIs rely on SOAP.
Pros
- Supports robust requirements like security, transactions etc
- Formal contracts reduce ambiguity
- Broad tools and skills availability
Cons
- More complex, verbose payload format
- Primarily used for internal rather than external access
- Challenging firewall traversal
Behind corporate walls, SOAP serves as a versatile workhorse to connect systems.
GraphQL: Flexible Data Fetching
GraphQL created by Facebook provides a modern spin on API architecture using:
- A strongly-typed schema defining available data and operations
- A query language for clients to request what they want
- A server to fulfill requests
Adoption: GraphQL usage expanding rapidly across web and mobile apps.
Pros
- Efficient data fetching getting just what you need
- Structured schemas aid documentation
- issuer/subject/audience typing helps rapid development
Cons
- Learning curve around need for valid queries
- Requires clients handle responses
- Additional tooling requirements
GraphQLs flexible and efficient data fetching model appears poised for growth.
gRPC: High Performance RPC
gRPC provides a modern take on RPC (Remote Procedure Call) using:
- Protocol Buffers IDL to define interfaces
- Binary serialization for efficient payloads
- Bi-directional streaming allow flexible dataflows
Adoption: gRPC used across Google cloud services and rapidly gaining steam.
Pros
- Efficient binary encoding
- Defined interfaces enable documentation generation
- Flexibility around unilateral, server, client streaming
Cons
- Requires gRPC libraries on client/server
- Mostly inter-system usage over internet
- Additional tools required to exploit capabilities
For inter-system communication gRPC delivers high-performance combined with interface contracts.
This visual map highlights some of the most widespread API archetypes in use today. Of course many other niche species including MQTT, SMPP, OData, and proprietary APIs exist in the wild. But understanding these common API architectures provides a solid foundation.
Now that we‘ve surveyed the API landscape, let‘s examine how to match API traits to use cases.
Matching APIs to Your Needs
With this field guide in hand, we can match technical traits to contexts to select the best API for particular jobs.
Several key considerations play a role in effectively making API decisions:
For example:
- If broad external access matters most, lean towards public REST APIs
- If security is paramount, lean towards private SOAP APIs
- If real-time data is critical, lean towards Webhooks
- If flexible queries over structured data is useful, lean towards GraphQL
While no API solves every need, consciously evaluating options against requirements makes it simpler to isolate options and zero in on appropriate candidates.
Of course alternative methods like screening APIs in the wild, examining tracks and traces, and running controlled integration tests can further validate optimal options.
Key Takeaways
Like organisms in an ecosystem, APIs now proliferate enabling modern applications to thrive. This guide covered key distinguishing traits across species of APIs including:
Access Models
- Public APIs — open access promotes innovation
- Internal APIs — secured within company walls
- Partner APIs — limited external partner access
- Composite APIs — simplified access to internal capabilities
Architectures
- REST — simple, scalable, leverages web standards
- SOAP — robust but complex enterprise integration
- GraphQL — efficient and flexible data fetcher
- gRPC — high-performance, contract-first RPC
Understanding these distinctions allows builders to critically evaluate options and match the right API model to their needs, avoiding common pitfalls.
While subtleties exist across implementations, identifying access models and architectures provides a framework for narrowing the playing field. From there specific analyses around performance, security, tooling and other practical considerations can guide final API selections.
So now that you can tell your RESTs from your RPCs, SOAPs from your GraphQLs, this field guide should help navigate the wilderness to find and capture APIs well suited to your needs.
