By the end of the lesson, you can say what a web API is, how it differs from an HTML page, what an API contract means, and why an API also needs access control.
Why do we need an API?
So far the server has delivered HTML pages, which the browser displayed. But a service can have many kinds of consumers: a program running in the browser, a mobile app, another server, a data-analysis script. These need not a displayed page but data and operations, in a form that a program can process. An API is a connection point built for programs like this. If every client had to figure out the inside of the service "by hand", the system would be brittle; the API defines what can be requested and what can be expected in response.
A web API is an API reached through web technologies, typically over HTTP. It is not a separate network protocol instead of HTTP: it uses the same requests, methods, status codes, and headers (chapter 2).
Two consumers of the course list
A university service shows the courses both on a web page and in a mobile app. The two interfaces differ, but they can build on the same course data. The server returns the data through the API, and each client displays it in the way that suits its own interface.
flowchart LR
W[Web client] --> A[Course API]
M[Mobile client] --> A
A --> S[Application rules and data]
The diagram shows a common connection point. It does not mean that every client displays the same screen, nor that the API publishes the tables of the database unchanged: behind the API, checks, authorization, and business rules also operate.
Here is a request and response for a simplified API of Kurzuspont (the output of the trial server, shortened):
The application/json type in the header indicates that the body is structured data. The client reads the cim field and displays it.
What does "contract" mean?
The contract of an API describes which operations are available, at which path and with which HTTP method, what data the request accepts, what structure the response has, and which status codes and errors it can return. When the client builds on this agreement, the server and the client can be developed separately. If the server unexpectedly sends a different field name, the client's interface can break even if the network and HTTP work flawlessly (lesson 5.6 goes into this).
The contract is not necessarily written in a machine-readable language, but documentation is part of it in any case. The client needs to know which data is mandatory, what may be missing, how the server signals an error, and which version to expect.
Separating data from presentation
If the server sends an HTML page, a large part of the presentation is in the response. A data API usually gives structured data, from which the client builds the interface or does further processing. The separation provides flexibility (the same data on several interfaces), but also new responsibilities: the client must handle the loading state, the error, and missing data; the server must offer a stable, understandable contract.
Public and internal APIs
Worked example: the API of Kurzuspont
The two clients of Kurzuspont are the browser interface and a student mobile app. Both use the same GET /api/kurzusok request and receive the same fields. The contract fixes the following:
Element
Contract
Endpoint
GET /api/kurzusok is the list, GET /api/kurzusok/{id} is one course
Response
JSON, with the fields id, cim, ferohely, jelentkezett
Error
status code + JSON error body
Access
the list is public, enrolment requires login
In the following steps the developer defines the format (5.2), the resource model (5.3), and the handling of changes (5.5, 5.6). (The id here is deliberately an identifier string, not a number.)
Common misconceptions
Statement
Clarification
"An API is opening a database directly to the internet."
The service gives data and operations according to its own rules.
"An API works instead of HTTP."
A web API typically uses HTTP messages.
"An API is needed only for mobile apps."
Browser-based, server-side, and other clients use it too.
"If the response is 200, the client surely understands it."
The structure of the response must also match the contract.
"A non-public API needs no protection."
An internal API is also protected by authorization checks.
In brief
A web API is a connection point built for programs, reachable over HTTP.
The contract fixes the endpoints, the input, the response, and the errors.
An API separates data from presentation, so several clients can be served.
Public and internal APIs alike need identification and authorization checks.
Review questions
How does an API response differ from the response of an HTML page?
What does an API contract contain?
Why can a client break if the server renames a field?
What is a web API?
Objectives
By the end of the lesson, you can say what a web API is, how it differs from an HTML page, what an API contract means, and why an API also needs access control.
Why do we need an API?
So far the server has delivered HTML pages, which the browser displayed. But a service can have many kinds of consumers: a program running in the browser, a mobile app, another server, a data-analysis script. These need not a displayed page but data and operations, in a form that a program can process. An API is a connection point built for programs like this. If every client had to figure out the inside of the service "by hand", the system would be brittle; the API defines what can be requested and what can be expected in response.
A web API is an API reached through web technologies, typically over HTTP. It is not a separate network protocol instead of HTTP: it uses the same requests, methods, status codes, and headers (chapter 2).
Two consumers of the course list
A university service shows the courses both on a web page and in a mobile app. The two interfaces differ, but they can build on the same course data. The server returns the data through the API, and each client displays it in the way that suits its own interface.
flowchart LR W[Web client] --> A[Course API] M[Mobile client] --> A A --> S[Application rules and data]The diagram shows a common connection point. It does not mean that every client displays the same screen, nor that the API publishes the tables of the database unchanged: behind the API, checks, authorization, and business rules also operate.
Here is a request and response for a simplified API of Kurzuspont (the output of the trial server, shortened):
The
application/jsontype in the header indicates that the body is structured data. The client reads thecimfield and displays it.What does "contract" mean?
The contract of an API describes which operations are available, at which path and with which HTTP method, what data the request accepts, what structure the response has, and which status codes and errors it can return. When the client builds on this agreement, the server and the client can be developed separately. If the server unexpectedly sends a different field name, the client's interface can break even if the network and HTTP work flawlessly (lesson 5.6 goes into this).
The contract is not necessarily written in a machine-readable language, but documentation is part of it in any case. The client needs to know which data is mandatory, what may be missing, how the server signals an error, and which version to expect.
Separating data from presentation
If the server sends an HTML page, a large part of the presentation is in the response. A data API usually gives structured data, from which the client builds the interface or does further processing. The separation provides flexibility (the same data on several interfaces), but also new responsibilities: the client must handle the loading state, the error, and missing data; the server must offer a stable, understandable contract.
Public and internal APIs
Worked example: the API of Kurzuspont
The two clients of Kurzuspont are the browser interface and a student mobile app. Both use the same
GET /api/kurzusokrequest and receive the same fields. The contract fixes the following:GET /api/kurzusokis the list,GET /api/kurzusok/{id}is one courseid,cim,ferohely,jelentkezettIn the following steps the developer defines the format (5.2), the resource model (5.3), and the handling of changes (5.5, 5.6). (The
idhere is deliberately an identifier string, not a number.)Common misconceptions
In brief
Review questions
Learning resources