Implementing REST Integration Exactly to Spec

Goal

You read an interface specification and implement a REST client exactly as written, equipped with pre-send validation, error code mapping, timeout handling, and integration logging.

Why it matters

In synchronous REST integration, what is really hard is not the call but when the other side is slow or strange. If you set a long connect timeout, the other side's outage becomes our outage, and if you do not decide an action for each error code, you resend wrong data 100 times or the business stops on a temporary outage. And if you do not validate before sending, our errors pile up in the other system's logs and the emotional drain between integration owners begins. "We block bad data on our side" is the basic courtesy of integration development.

Steps

Read /opt/lab/fixtures/eai/spec/IF-ORD-001.md and create /root/eai/spec.csv. The first line is field,type,length,required. Transcribe all the request items of the specification in ascending field-name order. required is Y/N.
Start the other system. python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200 (in the background) Save the response of http://127.0.0.1:9200/health to /root/eai/health.json. The status value must be UP.
Send one normal order as specified with POST /api/v1/orders and save the response to /root/eai/res-ok.json. resultCode must be 0000.
Create /root/eai/validate.sh. It takes one argument (a JSON file path), validates against the specification, and exits with code 0 if there are no problems; if there are, it prints the reason on the first line and ends with a non-zero exit code. It must catch at least three things: missing required, length exceeded, letters in a numeric field.
Create /root/eai/errmap.csv. The first line is code,meaning,action. Include every response code defined in the specification, and action is one of 재시도 (retry), 중단 (stop), or 통보 (notify).
http://127.0.0.1:9200/api/v1/slow responds with a 5-second delay. Call it with a 2-second timeout to make it fail, and create /root/eai/timeout.txt. It has two lines.
```
exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>
```
Create /root/eai/send.sh. It takes one argument (an order number), calls as specified, and prints the response's resultCode on the first line. If 0000, exit code 0; otherwise end with a non-zero exit code.
Create /root/eai/if.log. 7 fields separated by pipes (|), 3 or more lines.
```
시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID
```
The interface ID is IF-ORD-001, and the trace ID must differ from line to line.

Notes

POST: curl -s -X POST -H 'Content-Type: application/json' -d @파일 <URL> (the placeholder is the file)
Timeout: curl --max-time 2 ... / check the exit code with $?
Elapsed time: curl -w '%{time_total}'
Common mistake 1: judging success if the HTTP status is 200. Business errors often come as 200 + resultCode.
Common mistake 2: doing the length validation in characters. If the specification is in bytes, you must count in bytes.
Common mistake 3: using a fixed value for the trace ID. It must differ per call to allow matching.

Extract items from the specification

Read /opt/lab/fixtures/eai/spec/IF-ORD-001.md and create /root/eai/spec.csv. The first line is field,type,length,required. Transcribe all the request items of the specification in ascending field-name order. required is Y/N.

Read the specification and transcribe required/optional, type, and length into a table. This table becomes the specification for the validation logic in the next step.

Start and check the other system

Start the other system. python3 /opt/lab/fixtures/eai/rest/partner_api.py 9200 (in the background) Save the response of http://127.0.0.1:9200/health to /root/eai/health.json. The status value must be UP.

The first step of integration development is always "is the other side alive?" If there is a health check endpoint, check that first.

A normal call

Send one normal order as specified with POST /api/v1/orders and save the response to /root/eai/res-ok.json. resultCode must be 0000.

You must match the Content-Type exactly. Note that the response code field is separate from the HTTP status code - business errors often come as HTTP 200.

Pre-send validation script

Create /root/eai/validate.sh. It takes one argument (a JSON file path), validates against the specification, and exits with code 0 if there are no problems; if there are, it prints the reason on the first line and ends with a non-zero exit code. It must catch at least three things: missing required, length exceeded, letters in a numeric field.

Blocking bad data on our side is the basis of integration development. Distinguish three cases, missing required, length exceeded, and format mismatch, and print the reason.

Error code mapping table

Create /root/eai/errmap.csv. The first line is code,meaning,action. Include every response code defined in the specification, and action is one of 재시도 (retry), 중단 (stop), or 통보 (notify).

The key is to attach to each code which of "retry/stop/notify" it is. Without this distinction, developers retry everything or give up on everything.

Reproduce a timeout

http://127.0.0.1:9200/api/v1/slow responds with a 5-second delay. Call it with a 2-second timeout to make it fail, and create /root/eai/timeout.txt. It has two lines.

exit_code=<curl 종료코드>
policy=<타임아웃 시 처리 방침 한 줄>

curl has an option that limits the total time. If you check which exit code curl gives on a timeout, you can branch on it in a script.

Integration client script

Create /root/eai/send.sh. It takes one argument (an order number), calls as specified, and prints the response's resultCode on the first line. If 0000, exit code 0; otherwise end with a non-zero exit code.

You must give different exit codes depending on the response code so that the caller can decide. Test both success and failure.

Integration log standard

Create /root/eai/if.log. 7 fields separated by pipes (|), 3 or more lines.

시각|인터페이스ID|송신시스템|수신시스템|응답코드|소요ms|추적ID

The interface ID is IF-ORD-001, and the trace ID must differ from line to line.

The trace ID is the only key used to match against the other system's logs. It must differ per call, and it is meaningful only if it is also sent along in the request.