Spring Boot services · Chapter 35 of 41
Calling other services with RestClient
By the end of this chapter you can call another service over HTTP with RestClient, give each of its answers a meaning in your own code, and make sure no call waits forever. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Production
- 5 tasks
- Spring Boot
- In the all labs plan
The first 2 chapters of Spring Boot services are free. This one comes with the all labs plan.
Why you need this
Tapri has signed with a partner payment gateway: a counter takes a UPI payment, and Tapri Cloud confirms it with the gateway. The gateway is someone else's server. It answers in JSON, it says no in its own words ("Insufficient balance"), and on a bad morning it does not answer at all. Last week the old code waited four minutes for it while the queue at Mumbai CSMT reached the platform.
So far your code has only answered HTTP calls. Today the starter's pay endpoint fails for every order:
$ curl -i -X POST localhost:8081/orders/A1/pay -H "Content-Type: application/json" -d '{"amount": 120, "method": "UPI"}'
HTTP/1.1 500
Content-Type: application/json
Transfer-Encoding: chunked
Date: Wed, 07 Oct 2026 13:23:10 GMT
Connection: close
{"timestamp":"2026-10-07T13:23:10.147Z","status":500,"error":"Internal Server Error","path":"/orders/A1/pay"}
A counter cannot tell "the customer's bank said no" from "the gateway is down" from "our bug", and that decides whether to ask for cash.
What you build: 5 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
PaymentsConfig.java: point the client at the gateway and GET a payment
Build the paymentsClient bean from Spring Boot's RestClient.Builder with the gateway's base URL, read from the property tapri.payments.url (http://payments.tapri.test). Then write PaymentClient.status(paymentId) so it sends GET /payments/{id} to the gateway and reads the answer as a Payment.
status("TXN1") calls GET http://payments.tapri.test/payments/TXN1 and returns Payment("TXN1", "A1", 120, "PAID").
- Task 2
PaymentClient.java: charge an order by POSTing JSON
Write PaymentClient.charge(request) so it sends POST /payments to the gateway with the ChargeRequest as a JSON body (Content-Type application/json, exactly {"orderId":"A1","amount":120,"method":"UPI"}), and returns the Payment the gateway answers: Payment("TXN9", "A1", 120, "PAID"). Needs task 1.
- Task 3
PaymentClient.java: turn a 4xx into a declined payment
When the gateway answers charge with any 4xx status, throw PaymentDeclinedException with the gateway's reason as its message: the message field of the gateway's JSON error body. A 422 with {"message":"Insufficient balance"} throws PaymentDeclinedException("Insufficient balance"), not Spring's HttpClientErrorException.
- Task 4
PaymentClient.java: a 5xx or no answer means the gateway is down
Make charge throw PaymentUnavailableException when the gateway answers any 5xx status (a 503, say), and when it does not answer at all: a refused connection, an unknown host or a timeout, which RestClient throws as a ResourceAccessException.
In application.properties, set the timeouts for every HTTP client Spring Boot builds: give up connecting after 1 second and waiting for an answer after 2 seconds.
- Task 5
PaymentController.java: answer 201, 402 or 503
Make POST /orders/{orderId}/pay answer 201 Created with a Location header of /payments/{payment id} (/payments/TXN9) and the Payment as the body.
A declined payment answers 402 Payment Required with a ProblemDetail whose detail is the gateway's reason ("UPI limit reached"); a gateway that is down answers 503 Service Unavailable with a ProblemDetail (its status field 503). Needs tasks 2 to 4.
What you will learn
- RestClient: Spring's HTTP client, built once from Spring Boot's builder.
- Requests and answers: a GET or a POST, with JSON read and written for you.
- Errors: a 4xx, a 5xx and no answer at all, each with its own meaning.
- Timeouts: so no call waits longer than you choose.
More in Production
Build "Calling other services with RestClient" yourself
Tapri Cloud: the counters’ Java grows into a Spring Boot service with a database. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Spring Boot services are free. This one comes with the all labs plan.