Skip to content
Knowledge Hub/Article
Article

What Is an API? REST APIs, API Gateways and API Security

We explain how APIs work, HTTP methods and status codes, REST and OpenAPI, GraphQL and gRPC, API gateways, authentication and API security.

Oğuzhan Gerçek··10 min read
What Is an API? REST APIs, API Gateways and API Security

Short answer: An API (application programming interface) is the contract a piece of software offers to other software, defining which request gets which response. In a web API, the client sends a request such as GET or POST over HTTP, and the server answers with a status code and data. REST is one of the architectural styles these APIs build on, and OpenAPI is a standard for writing that contract down. An API gateway sits in front of the APIs and handles routing, authentication and rate limiting. The top risk on OWASP's API security list is a user changing the object ID in a request and reaching someone else's data.

What is an API?

API stands for application programming interface. NIST's glossary defines it as a system access point or library function with a well-defined syntax that application programs can access. As AWS puts it, APIs let two software components communicate using a set of definitions and protocols: the application sending the request is the client, and the one sending the response is the server. A mobile app, for example, sends a request to the API's address instead of connecting to the database directly with an SQL query; as long as the contract holds, the app keeps working even when the server side changes. You can find a short definition in our glossary.

Web APIs: HTTP methods and status codes

Web APIs run over HTTP, whose semantics are defined in RFC 9110 (June 2022, STD 97). Here are the main methods, with definitions from MDN and properties from the IANA registry:

  • GET: Requests a representation of a resource; safe and idempotent.
  • POST: Submits data to a resource, often changing state on the server; neither safe nor idempotent.
  • PUT: Replaces the resource entirely with the request content; idempotent.
  • PATCH (RFC 5789): Applies partial modifications; not idempotent.
  • DELETE: Deletes the resource; idempotent.

A safe method does not alter the server's state. Sending an idempotent request several times has the same effect as sending it once, so a client can safely retry it when it is unsure whether the request arrived. The first digit of a status code gives its class: according to IANA, 2xx means success, 4xx a client error and 5xx a server error. A 401 says the request lacks valid credentials; a 403 says the credentials may be valid but the client lacks permission. A sample request and response look like this:

GET /v1/customers/1042 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer <access-token>

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1042, "name": "Example Ltd.", "status": "active"}

Bearer token usage is defined in RFC 6750. We explain how a request reaches a web server in our web server article and how the connection is encrypted in our SSL article.

What is a REST API?

REST (Representational State Transfer) is an architectural style. Roy Fielding defined it in his doctoral dissertation, completed at the University of California, Irvine in 2000. According to chapter 5, its constraints are:

  • Client-server: User interface concerns are separated from data storage concerns.
  • Stateless: Each request carries all the information needed to understand it.
  • Cache: A response is labeled as cacheable or non-cacheable.
  • Uniform interface: Resources are identified and manipulated through representations.
  • Layered system: Each component sees only the layer it talks to directly; intermediaries can add load balancing.
  • Code-on-demand: Clients can download and run scripts; the only optional constraint in the dissertation.

According to AWS, RESTful APIs are HTTP-based, enable stateless client-server communication and use standard HTTP methods. The response in the example uses JSON. According to RFC 8259 (December 2017, STD 90), JSON is a lightweight, text-based, language-independent data interchange format.

OpenAPI: writing the API contract

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs, so both humans and computers can understand what a service can do without access to its source code. An OpenAPI document can be written in JSON or YAML. Documentation and code generation tools, as well as testing tools, work from it, and those tests can also run in a CI/CD pipeline. Version 3.2.0 was published on September 19, 2025, and its first patch release, 3.2.1, followed on September 10, 2026. The specification is based on the Swagger Specification donated by SmartBear Software.

GraphQL, gRPC and webhooks

REST is not the only option:

  • GraphQL: According to its current specification (September 2025 edition), a query language and execution engine for data models. The request is shaped like the data in its response, and the response contains exactly what the client asks for and no more.
  • gRPC: An open-source RPC (remote procedure call) framework and a CNCF incubation project. A client calls a method on a server on another machine as if it were a local object, using Protocol Buffers for messages by default and HTTP/2 for transport.
  • Webhook: When an event occurs, the provider sends an HTTP request to a URL you specified in advance. According to GitHub, webhooks take less effort and fewer resources than polling an API.

What is an API gateway?

An API gateway is the entry point between clients and backend services. According to the Azure API Management documentation, all requests reach the gateway first; acting as a facade, it lets the provider evolve the backend without affecting API consumers. Its jobs include:

  • Accepting calls and routing them to the right service
  • Verifying API keys, JWTs and certificates
  • Enforcing usage quotas and rate limits, and caching responses
  • Emitting logs, metrics and traces (see our log article)

In a microservices architecture, services communicate through well-defined APIs and are deployed independently, and clients call the gateway instead of the services. We cover packaging services as containers in our Docker article and running them in our Kubernetes article, and we operate this layer in our Application Runtime & Middleware Operations service.

API authentication: API keys, OAuth 2.0 and JWT

  • API key: A secret value that identifies the client. According to OWASP, API keys can reduce the impact of denial-of-service attacks, but you should not rely on them alone to protect sensitive resources, and keys belong in a header, not in the URL.
  • OAuth 2.0: Under the framework defined in RFC 6749 (October 2012), an application gets limited access to an HTTP service with an access token instead of the user's password. RFC 9700 (January 2025, BCP 240) says clients should not use the implicit grant and must not use the resource owner password credentials grant, in which the password goes directly to the client.
  • JWT: According to RFC 7519 (May 2015), a compact token that carries claims and can be signed or encrypted. OWASP says unsecured tokens ("alg":"none") must not be accepted.

We cover OpenID Connect, the identity layer on top of OAuth 2.0, and the principle of least privilege in our IAM article.

API security: the OWASP API Security Top 10 and rate limiting

The first five entries of the OWASP API Security Top 10 2023, published on June 5, 2023, are:

  1. API1:2023 Broken Object Level Authorization: An attacker can change the object ID in a request and reach someone else's record; OWASP calls for an authorization check in every function that accesses a record based on client input.
  2. API2:2023 Broken Authentication: Flawed authentication that lets attackers compromise tokens.
  3. API3:2023 Broken Object Property Level Authorization: Missing authorization checks on individual object properties.
  4. API4:2023 Unrestricted Resource Consumption: No limits on the CPU, memory, storage and bandwidth that requests consume.
  5. API5:2023 Broken Function Level Authorization: Authorization flaws that come from an unclear separation between administrative and regular functions.

The remaining entries cover risks such as SSRF, security misconfiguration and improper API inventory. Against API4, OWASP recommends rate limiting; when a limit is exceeded, the server returns 429 Too Many Requests, defined in RFC 6585 (April 2012), and a Retry-After header can say how long to wait. Because object level authorization is usually implemented in code, a WAF may treat a request for someone else's record as an ordinary request. We cover this layer in our application security (WAF) service.

Versioning, backward compatibility and integration

According to Google's AIP-180, APIs are contracts with users, and a minor or patch release must not break existing client code. Adding a field or method is backward compatible; removing or renaming a component, or changing its type or default value, is not. AIP-185 puts the major version in the URI path (such as v1) and does not expose minor or patch numbers. A deprecated version can be announced with the Deprecation header from RFC 9745 (March 2025), while the Sunset header from RFC 8594 shows when a URI is likely to stop responding.

We explain how APIs connect SaaS applications in our SaaS article and bulk data movement in our ETL article. The retry logic of an integration should account for idempotent methods and the Retry-After header. We handle API integration between systems in our system integration service.

Frequently asked questions

What does API stand for? Application programming interface: the request-and-response contract one piece of software offers to others.

What is a REST API? An HTTP-based API that follows the REST architectural style. Resources are identified by URIs and handled with methods such as GET, POST, PUT and DELETE.

What is GraphQL? A query language and execution engine for APIs. The client names the fields it wants in the query, and the response contains only those.

What is an API gateway? The entry point in front of APIs. It routes requests to the right service, verifies credentials and enforces rate limits.

Sources