5.3Webservices, REST APIs & exchanges
The essentials in 30 seconds
- REST APIs are the exchange standard: Yacine consumes a supplier's API for prices and exposes a service for the e-commerce site's orders, in JSON over HTTP.
- The REST vocabulary must be mastered: URL, GET/POST/PUT/DELETE methods, authentication token never hard-coded and return codes systematically handled.
- Robustness comes first: never trust received data, plan timeouts, retries, queues, idempotence and exchange logging.
Running mini-case — Yacine connects his management system to partner APIs
Yacine develops the management application for an electrical equipment trading SME in Oran. To avoid re-entering prices, he queries a supplier's REST API: a GET returns an item's price and stock in JSON format. For the distributor's e-commerce site, he exposes an API himself that receives orders via POST and returns their status. The authentication token is not written in the code: it is read from a secure parameter. Every response is validated before saving, because a zero price or an unknown item code must never enter the database. When the supplier is unavailable, the request goes into a queue and will be replayed with a unique identifier to avoid duplicates. Yacine logs every call: date, direction, service, return code and summarized data.
Standalone case for this section: it returns in the course, the diagram, the code and the 48h challenge of section 5.3.
1. Consume and expose
A management application rarely lives in isolation: it exchanges with accounting, an ERP, an e-commerce site, a bank or a supplier. Webservices and REST APIs are the modern standard. Consuming an API means calling a remote service to obtain or send data; exposing an API means publishing your own so that other applications can call it. Exchanges are most often in JSON over HTTP. Exchange files (CSV, XML, JSON, Excel) remain useful for batch imports and exports, and direct access to another database still exists, but the REST API is the preferred mode for real time.
2. The REST vocabulary
To call an API, Yacine identifies the service URL and the method: GET to read, POST to create, PUT to modify, DELETE to delete. Authentication often relies on a key or token: these secrets must never be hard-coded in the code or exposed on the client side. The data format (most often JSON) must be parsed and converted into business objects. Finally, return codes indicate success, an authentication error, a resource not found or a server error: they are handled systematically. A 200 code does not guarantee that the data is correct, and a 500 code is no reason to give up without a trace.
3. Robustness and traceability
A remote service will one day be unavailable, slow or inconsistent. Yacine starts from this principle and plans a timeout, spaced retries, a queue so nothing is lost and asynchronous processing so the user is not blocked. Idempotence avoids duplicates when a send is repeated: a unique operation identifier lets the server recognize a request already processed. All received data is validated before saving. Finally, exchanges are logged: date, direction, service, return code, summarized data and business identifier. This is the only usable evidence in the event of a dispute with a partner, and the best tool for diagnosing an intermittent failure.
🔎 Concrete example — 🔎 Concrete example — Consuming the supplier price API
Yacine retrieves a price and refuses any inconsistent value:
// Consommation de l'API prix fournisseur
sURL est une chaîne = "https://api.fournisseur.dz/articles/" + SAI_CodeArticle
sReponse est une chaîne = RESTEnvoie(sURL, "GET", gsJetonFournisseur)
SI sReponse = "" ALORS
Erreur("Service fournisseur indisponible")
RENVOYER Faux
FIN
oArticle est un dynamic ArticleAPI
JSONVersObjet(sReponse, oArticle)
SI oArticle.PrixHT <= 0 ALORS
Erreur("Prix reçu invalide")
RENVOYER Faux
FIN
RENVOYER VraiResult: no zero or negative price enters Yacine's database.
Reflex: the token comes from a secure parameter, never from the source code.
Section vocabulary
- REST API
- Web service exposing resources via URLs and HTTP methods, often in JSON.
Simple example: Yacine queries the supplier's API for prices and stock.
What it is not: copying the price list into the application by hand.
Reflex: REST API = standardized real-time exchange.
- HTTP methods
- Verbs of the HTTP protocol: GET (read), POST (create), PUT (modify), DELETE (delete).
Simple example: Yacine uses GET to consult and POST to receive an order.
What it is not: doing everything with a single verb without distinguishing the action.
Reflex: the method describes the intent of the exchange.
- API token
- Authentication secret presented on each call to prove the application's identity.
Simple example: Yacine reads his token from a secure parameter.
What it is not: writing the token in plain text in the code or in a page.
Reflex: a secret is never hard-coded.
- Idempotence
- Property of an exchange that, repeated with the same identifier, does not create a duplicate.
Simple example: Yacine attaches a unique operation identifier to each order.
What it is not: sending the same order again after a network outage.
Reflex: idempotence = recovery without duplicates.
- Exchange log
- Timestamped trace of calls: direction, service, summarized data, return code and business identifier.
Simple example: Yacine checks the log to diagnose a refused price.
What it is not: recording no exchange and assuming everything is fine.
Reflex: the log is the evidence and the diagnostic tool.
In practice — In practice — Exchanging with other systems
- Identify the suitable mode: REST API for real time, CSV/XML/JSON files for batches, direct access to another database as a last resort.
- To consume an API, locate the URL, the method (GET/POST/PUT/DELETE), the authentication and the JSON format, without ever hard-coding the secret.
- Systematically handle return codes and failures (service unavailable, timeout) with retry, queue and idempotence.
- Validate all received data, log exchanges and check your obligations regarding transmitted personal data.
Step-by-step script — logging an exchange (10 min)
Yacine traces every supplier response so he can diagnose and prove.
A summary is logged if the data is bulky, but always the business identifier that links the exchange to the order.
Copy-paste template — my API exchange sheet
// Fiche d'échange — Yacine
// Service : API fournisseur matériel électrique
// URL : https://api.fournisseur.dz/articles/{code}
// Méthode : GET
// Authentification : jeton lu dans ParametreSecurise("API_FOURNISSEUR")
// Format : JSON (ArticleAPI)
// Codes traités : 200, 401, 404, 429, 500
// Robustesse : délai 10 s, 3 reprises espacées, file d'attente
// Idempotence : NumeroOperation unique
// Journal : date, sens, service, code, données résuméesSupplier prices
Yacine consumes a supplier's API to update prices and stock.
E-commerce order
Yacine exposes a POST API that receives orders from the partner site.
Accounting export
Yacine produces a CSV file for accounting when the API is unavailable.
Recovery after failure
Yacine queues sends and replays them with a unique identifier.
✓ Best practices
- Protect API tokens and keys outside the source code.
- Validate all received data before saving.
- Plan retries, a queue and a log from the very first exchange.
✗ Common pitfalls
- Hard-coding a secret in the application or a page.
- Trusting the 200 code without checking the data.
- Resending a request without an operation identifier and creating a duplicate.
Key takeaways
- REST APIs exchange JSON over HTTP, both when consuming and exposing.
- URL, methods, authentication and return codes form the REST vocabulary.
- Secrets are never hard-coded and received data is validated.
- Timeouts, retries, queues, idempotence and logs make exchanges robust.
48h challenge — apply it tomorrow
Like Yacine, call a public API with GET from a small WinDev project, parse the JSON and validate a field before saving it. Add an exchange log (date, service, return code, summarized data) and simulate a failure by disconnecting the network. Verify that the request goes into a queue and that resending does not create a duplicate.
- I can explain the difference between consuming and exposing an API.
- I know how to name HTTP methods and protect a token.
- I know how to make an exchange robust and logged.
Frequently asked questions
Why should exchanges with external systems be logged?
Because when a problem occurs, the log is the only evidence of what was sent and received, and when. It helps diagnose wrong data, an intermittent failure or an unannounced change at the partner. It is also used to recover after an incident by knowing exactly what happened, and to answer a dispute or an audit. Yacine logs the date, direction, service, return code, a summary of the data and the business identifier (order or invoice number). Without this identifier, the log is hard to link to the actual operation.
How do you make exchanges that depend on an external service robust?
By starting from the principle that the service will one day be unavailable, slow or inconsistent. You need a timeout so you do not block indefinitely, spaced and limited retries, a queue to keep unsent requests, asynchronous processing so the user is not blocked, and a unique operation identifier to make the send idempotent. All responses are validated before saving, and every exchange is logged. Yacine also plans clear information for the user when the exchange is deferred.
What should be done with data received from a supplier API before saving it?