# Ask for the contract, not the docs, when the client's API isn't REST

> SOAP, gRPC and GraphQL all rest on a strict contract file, which is the shortcut to a working first call within a day.

Original: https://fdetimes.net/en/guides/call-soap-grpc-graphql-first-day/

It is 9am on your first day at the client, and you ask for access to the order system's API. You may hear "we use SOAP", "there's an internal gRPC service" or "just call /graphql".

REST is an architectural style in which requests are stateless: each one carries everything the server needs to understand and process it. If REST is all you know, any of these three can sound like three weeks of reading documentation.

In practice it takes far less. All three protocols are built on a tightly structured contract, and that contract is the shortcut. If you ask for the right file and make the easiest possible call, you can have a successful call the same day.

For a Forward Deployed Engineer, this is worth practising before you go on site. The sooner you can call the client's systems, the sooner you have real data to work with instead of waiting.

## What should you have by the end of the day?

The goal is a one-page "integration card" for each system. It records the protocol, the contract file, a working sample call, the timeout you chose and what an error looks like. With it comes a small function in your codebase that the rest of the team can call.

You need little up front: network access to the client's test environment, credentials, and a language you write quickly in. gRPC lets the client and server be written in different languages, provided gRPC supports them. Whatever language the client's server uses, you do not have to change your stack.

The table below sums up what to do for each protocol. The last column is practical advice that applies to all three: make one bad call on purpose so you see the error response for yourself before you write any code to handle it.

| Protocol | Contract to ask for | First call to make | What to look at when testing errors |
|---|---|---|---|
| SOAP | WSDL file | One read-only operation with few parameters | The Fault element in the body |
| gRPC | .proto file | One unary RPC | Make one bad call and record the error the client returns |
| GraphQL | Schema (type system) | A query for two or three fields | Send a bad query and record the response |

## Step 1: do not ask "where is the API?", ask "where is the contract?"

Your first question shapes the whole day. For SOAP, according to SmartBear, a service must have a WSDL file that defines every operation along with its inputs and outputs. For gRPC, Protocol Buffers is both the serialisation format and the interface definition language (IDL), so the .proto file is the contract.

GraphQL is slightly different: the API is organised around types and fields rather than endpoints. Every GraphQL service defines a type system, and tools can use it to check a query's syntax before it runs. What you need to ask for is the schema, plus the endpoint address.

Check before moving on: you have the contract file and can find at least one read-only operation in it. If the client sends a PDF guide instead of a WSDL or .proto file, ask again. PDFs go out of date; the contract file is what the live system actually uses.

## Step 2: SOAP, read the envelope before the letter

SOAP is a standardised, tightly structured protocol whose messages are written in XML. According to the W3C's SOAP 1.2 Primer, each message sits inside an envelope, the body is a mandatory part of that envelope, and errors are reported through a Fault element. The skeleton looks like this (a simplified illustration; take the namespace and operation name from the client's WSDL):

```xml
<env:Envelope xmlns:env="(namespace for the client's SOAP version)">
  <env:Body>
    <GetOrder>
      <OrderId>A-1024</OrderId>
    </GetOrder>
  </env:Body>
</env:Envelope>
```

The namespace placeholder reads "namespace for the client's SOAP version". In the WSDL, pick a read-only operation with the fewest parameters. Send an order ID that really exists in the test environment so you get real data back.

Check: the response has an envelope and the body contains data. Then send a bad ID on purpose to see what a Fault looks like, and paste that sample into the integration card. Your error-handling code will later need exactly that structure.

## Step 3: gRPC, start with unary and leave streaming for later

According to the gRPC documentation, a client can call a method on a server on another machine directly, as if it were a local function. gRPC has four kinds of method. The simplest is unary: the client sends one request and gets one response back. That is the call to make first.

Open the .proto file and look for an `rpc` line where neither the request nor the response has the `stream` keyword. The snippet below is a hypothetical example to help you spot one:

```proto
// simplified illustration; service and message names are hypothetical
service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);              // unary: call this first
  rpc WatchOrders (stream Filter) returns (stream OrderEvent);  // leave for later
}
```

(The comments say: simplified illustration with hypothetical service and message names; call the unary method first; leave the streaming one for later.) Bidirectional streaming, where both sides send a sequence of messages over a read-write stream, is the hard part. You do not need it on day one.

Generate client code for your language from the .proto file, then open a channel. In gRPC terms, a channel is a connection to a server at a specific host and port. Per-call information, such as authentication headers, goes in metadata.

Check: the unary call returns an object of type `Order`. If the call is rejected, check the authentication metadata before you suspect your code.

## Step 4: GraphQL, ask only for what you need

GraphQL is both a query language for APIs and a server-side runtime. Because the API is built around types and fields, you decide the shape of the response in the query itself. Keep your first query small (the field names below are hypothetical; use the real ones from the schema):

```graphql
query {
  order(id: "A-1024") {
    id
    status
  }
}
```

When you are exploring a client's schema, the big advantage is validation before execution. The type system lets tools flag a malformed query before the request reaches the server. Letting the tooling point out your mistakes teaches you the schema much faster than reading it from start to finish.

Check: the response contains exactly the two fields you asked for, no more and no fewer. Then add fields one at a time as the use case requires.

## Step 5: wrap it with a timeout before calling it done

A call that works on your laptop is not yet an integration. The client's service may respond slowly or hang, and your code should not wait forever. gRPC lets the client set a deadline: the maximum time it is willing to wait for an RPC to complete. For SOAP and GraphQL, set an equivalent timeout on whichever HTTP client you use.

Write a function such as `get_order(order_id)` that hides the protocol underneath. It takes simple parameters, returns your own object, and raises one consistent type of error, whether the cause was a SOAP Fault or an error returned by the gRPC client.

Below is a simplified Python skeleton. The function `_call_client_system` ("call the client's system") is where you put the real SOAP, gRPC or GraphQL call from step 2, 3 or 4. The 5-second value is only an example:

```python
# simplified illustration: replace _call_client_system with your real call
class IntegrationError(Exception):
    pass

def get_order(order_id: str, timeout_s: float = 5.0) -> dict:
    try:
        raw = _call_client_system(order_id, timeout=timeout_s)
    except Exception as e:  # SOAP Fault, gRPC error, HTTP error, timeout...
        raise IntegrationError(f"get_order({order_id}) failed: {e}") from e
    return {"id": raw["id"], "status": raw["status"]}
```

(The comments say: replace `_call_client_system` with your real call; the exception covers SOAP Faults, gRPC errors, HTTP errors and timeouts. The error message reads "get_order(...) failed".)

Check: call `get_order` once with a valid ID and once with a bad one. The first call should return a clean two-field dict. The second should raise an `IntegrationError` with a readable message, not a page-long XML stack trace. Your team does not need to know whether XML or Protocol Buffers sits underneath.

**Key point:** Do not read all the documentation: get the contract, make the easiest call, then wrap it.

## Three mistakes that turn one day into a week

The most common mistake is starting with the hardest part. The client mentions a "real-time event stream" and you dive into bidirectional streaming, when a unary RPC would have been enough to prove the connection and pull data for a demo.

The second is ignoring errors. Many engineers test only the success path, then on demo day hit an unfamiliar SOAP Fault their code cannot handle. Sending a deliberately bad request on day one takes five minutes and can save an entire demo.

The third is calling without a time limit. With no deadline or timeout, one hung service hangs the whole pipeline with it, and you lose an afternoon looking for the bug in the wrong place.

## How do you put this skill on your CV?

When an FDE job description mentions "integrating with legacy systems" or "client internal APIs", do not just answer with "SOAP, gRPC, GraphQL" in your skills section.

Write a line about the outcome instead, such as "integrated a SOAP service via WSDL, wrapped it in a client with timeouts and Fault handling". Or link to a small repo with clients for all three protocols calling a server you built yourself.

At the client, the person people come to trust is not the one who knows the SOAP 1.2 specification by heart. It is the one who, before lunch on day one, posts a single line in the shared channel: "GetOrder works, here's some sample data."

**Try this week:**

- Write a mock .proto file with one unary RPC, build the server in one language and call it with a client written in another
- Find a public GraphQL API, read its schema and write a query that fetches only two fields
- Draft a one-page "integration card" template: protocol, contract, sample call, timeout, error sample

## Sources

- [Introduction to gRPC](https://grpc.io/docs/what-is-grpc/introduction/)

- [Core concepts, architecture and lifecycle | gRPC](https://grpc.io/docs/what-is-grpc/core-concepts/)

- [GraphQL | The API language for humans and agents](https://graphql.org/)

- [SOAP vs. REST: What API Testers and Developers Need to Know | SmartBear Learn](https://smartbear.com/learn/api-design/soap-vs-rest-apis/)

- [SOAP Version 1.2 Part 0: Primer (Second Edition)](https://www.w3.org/TR/soap12-part0/)

- [What is REST?: REST API Tutorial](https://restfulapi.net/)
