Understanding APIs and Web Services

Modern digital services rarely work in isolation. When you pay for a service through a mobile application, track a delivery, sign in with an existing account or view weather information on a website, several software systems may be communicating behind the scenes. APIs and web services provide the rules and mechanisms that make this communication possible.

Understanding these technologies is useful for developers, entrepreneurs, product managers and professionals who work with digital tools. You do not need to become a specialist in every programming language to understand the central ideas: what an API exposes, how a request is made, how a response is returned and how systems protect the data they exchange.

What Is an API?

API stands for Application Programming Interface. An API is a defined way for one software system to request information or actions from another system. It acts as an agreement between the two systems, specifying what can be requested, how the request should be structured and what kind of response can be expected.

A useful everyday comparison is a restaurant menu. The menu lists the available dishes and the information needed to order them, but it does not show how the kitchen prepares each meal. In this comparison, the customer is one software application, the menu is the API documentation, the waiter carries the request and the kitchen is the system that performs the work.

APIs are not limited to the internet. An operating system provides APIs that allow applications to access files, cameras, location services or notifications. A programming library also exposes functions that other code can use. However, when people discuss APIs in web development, they usually mean web APIs that allow applications to communicate over a network.

What Is a Web Service?

A web service is a software service made available over a network, commonly through the web, so that other applications can use it. Web services normally rely on established communication technologies such as HTTP, the same foundation used by browsers to request web pages.

The terms API and web service are closely related but are not identical. An API is the broader concept: it is an interface for interacting with software. A web service is an API that is delivered through a network using web-based technologies. In other words, every web service is an API, but not every API is a web service.

For example, a mobile application may use an online payment service through an HTTP API. By contrast, a desktop application may use a local operating-system API to access a printer without contacting the internet. Both are APIs, but only the first example is a web service.

Why APIs Matter in Web Development

APIs allow organisations to build systems in separate, manageable parts. A company can maintain a customer database, a payment system, a notification service and a reporting dashboard as distinct components. APIs allow these components to exchange information without exposing their internal code or database structure.

This approach creates several practical advantages:

• Integration: An application can connect to external services such as maps, email delivery, payment processing or identity verification.
• Reuse: The same back-end service can support a website, mobile application and internal business dashboard.
• Faster development: Developers can use an existing service rather than building every feature from the beginning.
• Separation of responsibilities: Teams can improve one part of a system without rewriting the entire product.
• Automation: Software can send information and trigger actions without manual data entry.

Consider an online shop serving customers in Nairobi, Accra or London. Its front-end may display products and collect orders, while separate APIs handle stock levels, payments, delivery updates and customer notifications. The customer experiences one service, but the underlying application may depend on several specialised systems.

How an API Request Works

Most web API communication follows a request-and-response pattern. A client sends a request, and a server processes it before returning a response. The client could be a browser, mobile application, command-line tool or another server.

A request usually contains the following elements:

• URL or endpoint: The address of the resource or operation, such as https://example.com/api/products.
• HTTP method: The type of action being requested.
• Headers: Additional information, such as the content type or authentication credentials.
• Parameters: Optional values used to filter, identify or customise the request.
• Request body: Data sent to the server, often in JSON format when creating or updating a resource.

The server then returns a response that may include a status code, response headers and a body containing data or an error message. A successful response might return a list of products, while an unsuccessful response might explain that a requested product does not exist or that the user is not authorised.

HTTP Methods and Their Meaning

HTTP methods help communicate the intended action. The most common methods in web development are:

• GET: Retrieve information without normally changing it. For example, retrieve a list of available courses.
• POST: Submit data to create a resource or trigger an operation. For example, create a new learner account.
• PUT: Replace an existing resource with a new representation. For example, replace all details in a customer profile.
• PATCH: Modify part of an existing resource. For example, update only a phone number.
• DELETE: Request the removal of a resource, where the system permits deletion.

These meanings help developers design predictable interfaces. A request such as GET /courses is easier to understand than an endpoint whose purpose cannot be inferred. Good design also considers whether an operation is safe to repeat. Repeating a GET request should normally not create a new record, while repeating a payment-related POST request may require special safeguards to prevent duplicate processing.

Common HTTP Status Codes

Status codes provide a quick indication of what happened. They do not replace a useful response message, but they help both people and software interpret the result.

• 200 OK: The request succeeded.
• 201 Created: A new resource was successfully created.
• 204 No Content: The request succeeded but there is no response body to return.
• 400 Bad Request: The request is invalid or contains missing and incorrectly formatted data.
• 401 Unauthorised: Authentication is missing or invalid.
• 403 Forbidden: The requester is identified but does not have permission to perform the action.
• 404 Not Found: The requested resource or endpoint cannot be found.
• 429 Too Many Requests: The client has exceeded an allowed request rate.
• 500 Internal Server Error: The server encountered an unexpected problem.

Applications should handle these results deliberately. For example, a 404 may lead the interface to show that a course is unavailable, whereas a 500 error may require a temporary retry and a message asking the user to try again later. Treating every error as the same makes systems confusing and difficult to support.

RESTful Web Services

REST, or Representational State Transfer, is an architectural style commonly used to design web APIs. REST is not a programming language or a single product. A RESTful API generally represents information as resources, uses standard HTTP methods and returns representations of those resources, often as JSON.

For an education platform, resources might include learners, courses and enrolments. Possible endpoints could include:

• GET /courses to retrieve available courses
• GET /courses/42 to retrieve one course
• POST /enrolments to create an enrolment
• PATCH /learners/17 to update selected learner details

REST APIs are popular because they use familiar web principles and are relatively easy to consume from browsers, mobile applications and back-end services. Well-designed REST APIs also use clear resource names, consistent response formats, meaningful status codes and thorough documentation.

SOAP Web Services

SOAP, which originally stood for Simple Object Access Protocol, is a formal messaging protocol used for exchanging structured information. SOAP commonly uses XML and defines rules for message structure, processing and errors. It is often associated with enterprise systems that require formal contracts and established standards.

SOAP can be more verbose than a typical REST API, but that formality can be useful in complex environments. Organisations may choose SOAP when they need strict service definitions, specific security standards or compatibility with existing enterprise software. The best choice depends on the system's requirements, not on the popularity of a particular technology.

REST and SOAP should not be treated as interchangeable labels. REST is an architectural style, while SOAP is a protocol. A technical team should consider data formats, security requirements, existing infrastructure, performance needs and the capabilities of the systems that must connect.

GraphQL and Other API Styles

GraphQL is an API query language and runtime that allows a client to request the specific fields it needs. Instead of calling several endpoints that return fixed data structures, a client may send a query describing the required combination of information.

This can be useful when different applications need different amounts of data. A mobile application using a slower connection may request only a course title and progress percentage, while a staff dashboard may request additional learner and assessment details. GraphQL can reduce unnecessary data transfer, but it also introduces design, monitoring and security considerations.

Other approaches include remote procedure call APIs, event-driven systems and webhooks. A webhook allows one system to notify another when an event occurs. For example, an ordering system could send a notification to a delivery application when an order is marked ready. Unlike a client repeatedly asking whether anything has changed, a webhook can deliver the event when it happens.

Authentication, Authorisation and Security

APIs often expose valuable or sensitive information, so access must be controlled. Authentication asks, “Who is making this request?” Authorisation asks, “What is this authenticated user or application allowed to do?” A system may identify a staff member successfully but still prevent that person from accessing another department's confidential records.

Common approaches include API keys, session-based authentication and token-based methods such as bearer tokens. The method should match the risk and purpose of the service. Credentials should not be placed in public source code, shared through unsafe channels or stored without suitable protection.

Secure API development also involves using HTTPS, validating incoming data, limiting request rates, recording relevant security events and returning only the information a client needs. Error messages should help legitimate developers troubleshoot without revealing passwords, private keys, database details or internal system paths.

Security is especially important when an API handles identity information, payments, health records, business data or learner records. A small application can still have serious security responsibilities, even if it has a modest number of users.

API Documentation and Versioning

An API is difficult to use if its rules exist only in the developer's memory. Documentation should explain available endpoints, methods, required fields, authentication, example requests, example responses, error conditions and any limits on usage. Clear documentation reduces integration time and prevents avoidable misunderstandings between teams.

APIs also change over time. A field may be renamed, an endpoint may be removed or a response may gain a new required value. These changes can break applications that depend on the earlier behaviour. Versioning, such as using a version identifier in an endpoint or request header, helps teams introduce changes in a controlled way.

Good version management includes communicating planned changes, providing migration guidance, allowing a reasonable transition period and monitoring which clients still use an older version. Compatibility should be treated as part of the service, not as an afterthought.

Applying This in Practice

Suppose you are building a small business application that records orders and sends delivery updates. A practical integration process could follow these steps:

1. Define the business need. Decide whether you need to retrieve information, create records, update records or receive event notifications.
2. Identify the data. List the fields required, such as order reference, customer contact, delivery location and order status. Avoid requesting data that the application does not need.
3. Study the provider's documentation. Check endpoints, authentication, request limits, test environments, expected status codes and pricing or service conditions.
4. Test with sample data. Use a safe development or sandbox environment where available. Test successful requests as well as missing fields, invalid credentials, duplicate submissions and unavailable services.
5. Build error handling. Decide what the user sees when a request fails and whether the application should retry. Do not retry every error automatically; an invalid request needs correction, while a temporary server problem may justify a controlled retry.
6. Protect credentials and data. Store secrets securely, use encrypted connections and restrict access according to user roles.
7. Monitor the integration. Record useful technical information, measure failures and watch for changes in the provider's documentation or service status.

For a Kenyan retailer, this might involve connecting an online catalogue to a stock system, a payment provider and a courier service. The technical details will vary, but the reasoning remains the same: define the interaction, understand the contract, protect the exchange and plan for failure.

Questions to Consider Before Choosing an API

• Does the API provide the exact operations and data the product requires?
• Is the documentation clear enough for another developer to follow?
• How are users and applications authenticated?
• What happens when the service is slow, unavailable or returns incomplete data?
• Are there request limits, usage costs or restrictions that affect the business model?
• How are changes announced and older versions supported?
• Can the organisation meet its responsibilities for protecting the data being exchanged?

Key Takeaways

• An API is a defined interface that allows software systems to interact; a web service is an API delivered through network and web technologies.
• Web APIs commonly use HTTP requests, methods such as GET and POST, structured data and status codes.
• REST, SOAP and GraphQL are different approaches with different strengths and design considerations.
• Authentication identifies a requester, while authorisation determines what that requester may do.
• Reliable integrations require clear documentation, deliberate error handling, secure credentials and version management.
• Before choosing an API, examine its capabilities, limits, security, costs and approach to future changes.