knowledge

Overview

A Web API (Application Programming Interface) is a set of rules that allows different software systems to communicate over the web. Web APIs act as the layer between a client (browser, mobile app, or another server) and a server’s data or functionality — defining what requests the server accepts, what format the data takes, and what the server will return. Understanding web APIs is essential for web security testing because APIs often expose sensitive functionality with weaker authentication than the main application, and may contain hidden or undocumented endpoints.

Terminology

TermDefinition
APIApplication Programming Interface — a contract defining how two systems communicate
EndpointA specific URL the server is configured to receive requests on and route to a handler
RESTRepresentational State Transfer — an architectural style using HTTP methods on resource URLs
SOAPSimple Object Access Protocol — XML-based messaging standard with formal structure
GraphQLA query language and runtime that serves all requests through a single endpoint
WSDLWeb Services Description Language — XML file describing a SOAP API’s operations and parameters
IntrospectionGraphQL feature that lets clients query the schema itself to discover all available types and operations
JSONJavaScript Object Notation — lightweight data format most REST APIs use for responses
XMLeXtensible Markup Language — structured data format used by SOAP and some REST APIs
CRUDCreate, Read, Update, Delete — the four standard operations REST maps to HTTP methods

Core Concepts

What Is an Endpoint?

This is a common source of confusion. An endpoint is not a separate program and it is not a standalone listener. Here is how it actually works:

A web server is a program running on the machine and listening on a port (usually 80 for HTTP or 443 for HTTPS). That server stays running and handles every incoming request. An endpoint is simply a routing rule inside that server — a configuration entry that says “if a request comes in for this URL path, run this piece of code and return the result.”

Think of it like a call centre:

  • The call centre building = the web server (always running, always answering)
  • The phone number = the IP address and port
  • The menu options (“press 1 for billing, press 2 for support”) = endpoints (routes the server knows about)
  • When you press 2 = sending a GET /support request
  • The support agent who picks up and reads from their knowledge base = the server-side code that runs, queries a database, and returns JSON

When a request hits /users/123, nothing new starts up. The already-running web server reads the URL path, matches it to a configured route, executes the associated handler function, and sends back the response — usually JSON or XML. The “endpoint” is just the address for that route, not a machine or a listener of its own.

REST — Representational State Transfer

REST is the dominant API style for web applications. It organises data as resources identified by unique URLs, and uses standard HTTP methods to define what action to take on that resource.

HTTP Methods → CRUD

HTTP MethodCRUD OperationExample
GETReadGET /users/123 — retrieve user 123
POSTCreatePOST /users — create a new user
PUTUpdate (full)PUT /users/123 — replace user 123
PATCHUpdate (partial)PATCH /users/123 — update one field
DELETEDeleteDELETE /users/123 — delete user 123

REST Endpoint Structure

REST endpoints follow a hierarchical URL pattern representing resources:

URLMeaning
/usersCollection of all users
/users/123Specific user with ID 123
/users/123/postsPosts belonging to user 123
/products/456/reviewsReviews for product 456

REST Parameter Types

Parameter TypeLocationPurposeExample
Query ParametersURL after ?Filtering, sorting, pagination/users?limit=10&sort=name
Path ParametersEmbedded in URLIdentify a specific resource/products/{id}
Request BodyPOST/PUT/PATCH bodyCreate or update a resource{ "name": "New Product", "price": 99.99 }

SOAP — Simple Object Access Protocol

SOAP is a formal, XML-based messaging standard. Unlike REST’s multiple endpoints, a SOAP API typically exposes a single URL — the content of the XML message determines what operation is performed. SOAP includes built-in support for security, reliability, and transaction management, which makes it common in enterprise and financial systems.

SOAP messages are wrapped in an Envelope structure:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Header/>
    <soapenv:Body>
        <lib:SearchBooks>
            <lib:keywords>cybersecurity</lib:keywords>
            <lib:author>Dan Kaminsky</lib:author>
        </lib:SearchBooks>
    </soapenv:Body>
</soapenv:Envelope>

The WSDL file (Web Services Description Language) describes the full API — available operations, input/output parameters, data types, and the endpoint URL. WSDL analysis is the first step when targeting a SOAP API.

GraphQL

GraphQL is a query language and server runtime that exposes a single endpoint (typically /graphql) through which clients make all requests. Unlike REST, the client specifies exactly what data it wants — no over-fetching (getting more than needed) or under-fetching (having to make multiple requests).

Queries — Fetch Data

query {
    user(id: 123) {
        name
        email
        posts(limit: 5) {
            title
            body
        }
    }
}

This retrieves the name, email, and first 5 post titles/bodies for user 123 in a single request.

Mutations — Modify Data

mutation {
    createPost(title: "New Post", body: "Content here") {
        id
        title
    }
}

Creates a new post and returns its id and title.

GraphQL Parameter Components

ComponentDescriptionExample
FieldA specific piece of data to retrievename, email
ArgumentModifies a query — for filtering or paginationposts(limit: 5)
RelationshipA connection between data typesuser → posts
Nested ObjectA field that returns another objectposts { title, body }

API vs Web Server

FeatureWeb ServerAPI
PurposeServe HTML/CSS/JS pagesExchange structured data between systems
Data FormatHTML, images, static filesJSON, XML
Primary ConsumerHuman users via browserOther applications and services
AccessUsually publicPublic, private, or partner-restricted
Examplehttps://example.com serving a login pageGET /api/users/123 returning {"name":"Alice"}

Endpoint Discovery Methods

Finding API endpoints — both documented and hidden — is the first step in API testing.

MethodWhat It Reveals
API Documentation (Swagger/OpenAPI/RAML)All documented endpoints, parameters, expected formats
WSDL Analysis (SOAP)All operations, input/output parameters, data types
GraphQL IntrospectionFull schema — types, fields, queries, mutations
Network Traffic AnalysisActual endpoints used by the application in practice
Parameter Name FuzzingHidden or undocumented endpoints via wordlist brute-force
JavaScript Source ReviewFrontend code often contains API routes in fetch/axios calls

References / Images