XML: Structuring Complex Data

From Isolated Programs to Connected Services

Modern software rarely works in isolation. A weather application may need data from a meteorological service, while a payment processor may need to verify a transaction with a bank. In each case, one application needs a controlled way to use a capability provided by another application.

An application programming interface, or API, provides that controlled connection. It is an application-to-application contract: a published set of rules describing how one program can access services provided by another program. The contract lets applications exchange requests and responses without requiring the consumer to understand the provider's internal implementation.

The Three Parts of an API Contract

Every API involves three essential elements. The service provider is the application offering a service. The API specification is the published set of rules. The service consumer is the application using that service. The consumer reads the specification and creates requests that follow its rules.

Following One API Request

1. The consumer application identifies the service it wants.
2. The consumer sends a request with any necessary parameters.
3. The provider application receives and processes the request according to the API rules.
4. The provider sends a response containing requested data or confirmation of an action.
5. The consumer uses the response without needing to know how the provider stores or processes its data internally.

This cycle takes place over HTTP, which acts as the transport protocol. The data carried in the cycle is represented using XML or JSON, formats that both applications can understand and parse. HTTP answers how the exchange travels; XML or JSON answers how the exchanged data is represented.

XML Inside the Exchange

XML is one of the data representation formats an API can use when applications exchange information. Its role is to represent the data in a form that both the consumer and provider can understand and parse. The API contract specifies the expected format, so the consumer can interpret the provider's response without learning the provider's internal storage system.

The hierarchy illustrates the organizing idea: a response can contain a larger piece of information, which can contain related pieces of information. For example, a weather service may expose separate services for the current temperature, a forecast, and historical data. The exact representation rules come from the API specification; the consumer should use those rules rather than assume how the provider organizes its internal data.

Transport and Representation

These technologies have different jobs. HTTP carries the communication between applications. XML and JSON represent the data being exchanged. The API specification establishes which services are available, what parameters are accepted, and what request and response formats the consumer should use.

Abstraction at the API Boundary

This abstraction protects the provider's internal systems because the consumer can access only the functionality explicitly exposed through the API. It also allows the provider to change its internal implementation without breaking consumers, provided the API contract remains the same. At the same time, the consumer's code is simpler because it only needs to learn the published API.

Mistakes About XML and APIs

• Treating XML as the transport mechanism

  HTTP is the transport protocol in the API exchange. XML is a data representation format.

  Fix: Describe HTTP as the transport and XML as one possible format for representing the exchanged data.

• Assuming the consumer needs access to the provider's internal system

  The API hides internal complexity and exposes only specified services.

  Fix: Focus on the published services, parameters, and request and response formats.

• Describing an API as only a piece of software

  The API is an application-to-application contract involving a provider, a published specification, and a consumer.

  Fix: Include the published rules and the applications on both sides of the exchange.

• Assuming every API uses XML

  The source identifies XML and JSON as data representation formats used in API communication.

  Fix: Say that an API may use XML or JSON according to its published specification.

Check Your Understanding

1. An API is an application-to-application contract that publishes rules for accessing services. The consumer sends a request, the provider processes it, and the provider returns data or confirmation according to the contract. HTTP transports the exchange, while XML or JSON represents the data. XML can organize complex exchanged information in a structured hierarchy, but the consumer still relies on the API specification rather than the provider's internal implementation.