Skip to content

Managing Stubs Using the REST API

Jump to bottom
Rodrigo edited this page Mar 6, 2021 · 3 revisions

The gRPC mock server is capable of returning any success or error response. Ir order for it to know what response to send for a specific request it is necessary to create stubs and it is done through its REST API. When the gRPC server starts, by default it is listening on two different ports: 1068 and 10010. Port 1068 is the REST API endpoint that we will use to manage the stubs.

The API consists of two endpoints:

The stubs stored in the server only live while the server is running. There is no provision to add support for persistent stubs storage. However, there is an open issue to add support to load stubs from the filesystem at start Issue #1.

Stubs endpoint

Endpoint: /stubs

Exposes a CRUD interface for stub management.

Add Stub

Method: POST

Body: Stub

Get Stubs

Method: GET

Query Params

method OPTIONAL

If provided returns the only the stubs added for the gRPC method. Otherwise returns all stubs.

Update Stub

Method: PUT

Body: Stub

Delete Stub

Method: DELETE

Deletes all stubs.

Optionally a method name can be provided as a query parameter, in that case all stubs stored for the provided method will be deleted.

Optionally a stub can be provided in the body, in that case only that stub will be deleted.

Body: Stub OPTIONAL

Query params

method OPTIONAL

If provided all the existing stubs for the provided method will be deleted.

Examples endpoint

Endpoint: examples

Returns auto-generated stub examples for all supported methods in the server.

Get examples

Method: GET

Stub

A stub has this basic structure:

{
    "fullMethod": "/carvalhorr.greeter.Greeter/Hello",
    "request": {
        "match": "exact | partial",
        "content": {},
        "metadata": {}
    },
    "response": {
        "type": "success | error",
        "content": {},
        "error": {
            "code": 0,
            "message": "",
            "details": {}
        }
    }
}

stub.fullMethod

The fun gRPC method name. The method names supported by the server are logged when the server starts up.

stub.request

The request definition to be matched against incoming gRPC requests.

stub.request.match

Determine how the stub will be matched against an incoming gRPC request. If it matches then the response is returned for the incoming request.

Possible values: exact or partial

If the stub defines the exact match mode then all the fields in an incoming request must match all the fields defined in the stub`s stub.request.content.

If the stub defines the partialmatch mode then only the fields defined in stub.request.content must match to the fields in an incoming request.

stub.request.content

The JSON definition of the request to be matched against incoming requests.

stub.request.metadata

Optionally, metadata can be used to determine if an incoming request matches a stub. If provided, the fields added to the metadata must match to the metadata in an incoming request.

Each metadata field is of type string. To provide multiple values, separate them by a comma.

stub.response

The definition of the response to return in case an incoming request matches the stub.

stub.response.type

Defines the type of response to return: success or error.

stub.response.content

The response content to return in case the field stub.response.type is success. This is the JSON that will be unmarshaled to the response type defined in the API.

stub.response.error

The error to be returned in case the request matches the stub and the field stub.response.type is error. Errors are described by status.Status.

stub.response.error.code

The error code. See Code. In addition to the defined error codes, any unsigned int 32 can be used.

stub.response.error.message

The error message.

stub.response.error.details

See Advanced error mocking to learn how to add details to the error response.

Clone this wiki locally