Skip to main content

API

Smocker's API is started on the port 8081 by default. This page lists all the administration endpoints of the server.

Reset Smocker​

Clear the mocks and the history of calls.

  • Endpoint: POST /reset
  • Query Parameters:
NameValuesDescription
forcetrue, falseOptional (defaults to false), used to remove even locked mocks on reset
  • Sample Response:
{
"message": "Reset successful"
}

Add Mocks​

  • Endpoint: POST /mocks
  • Query Parameters:
NameValuesDescription
resettrue, falseOptional (defaults to false), used to reset on Smocker before adding mocks.
sessionOptional, the name of the new session to start.
  • Headers:
NameValuesDescription
Content-Typeapplication/json, application/x-yamlOptional (defaults to application/x-yaml), the mime type of the payload.
  • Errors:

    • 400 Bad Request, if the payload cannot be parsed accordingly to the declared Content-Type,
    • 400 Bad Request, if the payload contains semantically invalid mocks,
    • 415 Unsupported Media Type, if the declared Content-Type is not supported.
  • Sample Body:

- request:
method: GET
path: /hello/world
response:
status: 200
headers:
Content-Type: application/json
body: >
{
"message": "Hello, World!"
}

- request:
method: POST
path: /hello/world
response:
status: 500
headers:
Content-Type: application/json
body: >
{
"message": "error"
}
  • Sample Response:
{
"message": "Mocks registered successfully"
}
tip

Mocks will be added one after the other.
Smocker stores its mocks in a stack and when a call comes, it will unstack them one by one to find a matching mock.
Therefore, the last mock in the list will be considered by Smocker as having the highest priority.

Get Mocks​

Retrieves the mocks declared into Smocker for a session (by default the last one).

  • Endpoint: GET /mocks
  • Query Parameters:
NameDescription
idOptional, the ID of the mock to retrieve.
sessionOptional, the ID of the session to which the mock(s) belong. (default: last session ID)
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 404 Not Found, if no mock with the given ID could be found.
    • 404 Not Found, if no session match the ID passed in parameter.
  • Sample Response:

[
{
"request": {
"method": "POST",
"path": "/hello/world"
},
"response": {
"status": 500,
"headers": {
"Content-Type": "application/json"
},
"body": "{\"message\": \"error\"}"
},
"context": {},
"state": {
"id": "b26ec829-1989-4c98-bbf7-f64b70c1a583",
"times_count": 2,
"creation_date": "2020-02-01T03:47:48.911213+01:00"
}
},
{
"request": {
"method": "GET",
"path": "/hello/world"
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"body": "{\"message\": \"Hello, World!\"}"
},
"context": {
"times": 1
},
"state": {
"id": "ffa3cd8d-779b-4814-9cb0-13b4717d987f",
"times_count": 1,
"locked": false,
"creation_date": "2020-02-01T03:47:48.911211+01:00"
}
}
]
tip

The mocks will be ordered from highest to lowest priority.

Lock Mocks​

Lock a list of mocks in order to make them reset proof.

  • Endpoint: POST /mocks/lock
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 400 Bad Request, if the payload cannot be parsed accordingly to the declared Accept,
    • 400 Bad Request, if the payload is not a mock ID list,
    • 500 Internal Server Error, if an error occurs when locking the mocks.
  • Sample Body:

["ffa3cd8d-779b-4814-9cb0-13b4717d987f"]
  • Sample Response:
[
{
"request": {
"method": "POST",
"path": "/hello/world"
},
"response": {
"status": 500,
"headers": {
"Content-Type": "application/json"
},
"body": "{\"message\": \"error\"}"
},
"context": {},
"state": {
"id": "b26ec829-1989-4c98-bbf7-f64b70c1a583",
"times_count": 2,
"creation_date": "2020-02-01T03:47:48.911213+01:00"
}
},
{
"request": {
"method": "GET",
"path": "/hello/world"
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"body": "{\"message\": \"Hello, World!\"}"
},
"context": {
"times": 1
},
"state": {
"id": "ffa3cd8d-779b-4814-9cb0-13b4717d987f",
"times_count": 1,
"locked": true,
"creation_date": "2020-02-01T03:47:48.911211+01:00"
}
}
]

Unlock Mocks​

Unlock a list of mocks in order to make them resetable.

  • Endpoint: POST /mocks/unlock
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 400 Bad Request, if the payload cannot be parsed accordingly to the declared Accept,
    • 400 Bad Request, if the payload is not a mock ID list,
    • 500 Internal Server Error, if an error occurs when locking the mocks.
  • Sample Body:

["ffa3cd8d-779b-4814-9cb0-13b4717d987f"]
  • Sample Response:
[
{
"request": {
"method": "POST",
"path": "/hello/world"
},
"response": {
"status": 500,
"headers": {
"Content-Type": "application/json"
},
"body": "{\"message\": \"error\"}"
},
"context": {},
"state": {
"id": "b26ec829-1989-4c98-bbf7-f64b70c1a583",
"times_count": 2,
"creation_date": "2020-02-01T03:47:48.911213+01:00"
}
},
{
"request": {
"method": "GET",
"path": "/hello/world"
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"body": "{\"message\": \"Hello, World!\"}"
},
"context": {
"times": 1
},
"state": {
"id": "ffa3cd8d-779b-4814-9cb0-13b4717d987f",
"times_count": 1,
"locked": false,
"creation_date": "2020-02-01T03:47:48.911211+01:00"
}
}
]

Get History​

Retrieves the history of calls made to Smocker for a session (by default the last one). For each call, the history entry will contains the request, the response, and if a matching mock has been found, its ID.

  • Endpoint: GET /history
  • Query Parameters:
NameDescription
filterOptional, a regex used to filter on the request path of the history entries.
sessionOptional, the ID of the session to which the mock(s) belong. (default: last session ID)
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 400 Bad Request, if the filter is an invalid regular expression.
    • 404 Not Found, if no session match the ID passed in parameter.
  • Sample Response:

[
{
"mock_id": "b95e93a1-7eeb-41a9-8cc2-0ff7dae588a2",
"request": {
"path": "/test",
"method": "GET",
"body": "",
"date": "2020-02-01T03:29:08.440521+01:00"
},
"response": {
"status": 200,
"body": {
"message": "test1"
},
"headers": {
"Content-Type": ["application/json"]
},
"date": "2020-02-01T03:29:08.440853+01:00"
}
},
{
"mock_id": "53a87695-6303-49ff-ae1c-b7b7591e3f3e",
"request": {
"path": "/test",
"method": "POST",
"body": "",
"date": "2020-02-01T03:29:08.445801+01:00"
},
"response": {
"status": 200,
"body": {
"message": "test2"
},
"headers": {
"Content-Type": ["application/json"]
},
"date": "2020-02-01T03:29:08.446337+01:00"
}
}
]

Get History Summary​

Retrieves a summary of the history of calls made to Smocker for a session (by default the last one).
For each call, it will contains:

- type: request, response or processing
- message: the request method + path + query params or the response status
- from: the caller
- to: the receiver
- date: date of the call
  • Endpoint: GET /history/summary
  • Query Parameters:
NameDescription
sessionOptional, the ID of the session to which the mock(s) belong. (default: last session ID)
srcOptional, a HTTP header used to determine source of calls. (default: empty)
destOptional, a HTTP header used to determine destination of calls. (default: empty)
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 404 Not Found, if no session match the ID passed in parameter.
  • Sample Response:

[
{
"type": "request",
"message": "GET /hello/world",
"from": "Client",
"to": "Smocker",
"date": "2020-06-05T03:25:04.3300161+02:00"
},
{
"type": "response",
"message": "666",
"from": "Smocker",
"to": "Client",
"date": "2020-06-05T03:25:04.3304084+02:00"
},
{
"type": "request",
"message": "POST /hello/world",
"from": "Client",
"to": "Smocker",
"date": "2020-06-05T03:25:09.6026761+02:00"
},
{
"type": "processing",
"message": "use response mock",
"from": "Smocker",
"to": "Smocker",
"date": "2020-06-05T03:25:09.603110099+02:00"
},
{
"type": "response",
"message": "500",
"from": "Smocker",
"to": "Client",
"date": "2020-06-05T03:25:09.6031101+02:00"
},
{
"type": "request",
"message": "GET /hello/world",
"from": "Client",
"to": "Smocker",
"date": "2020-06-05T03:25:09.6079179+02:00"
},
{
"type": "processing",
"message": "use response mock",
"from": "Smocker",
"to": "Smocker",
"date": "2020-06-05T03:25:09.608433499+02:00"
},
{
"type": "response",
"message": "200",
"from": "Smocker",
"to": "Client",
"date": "2020-06-05T03:25:09.6084335+02:00"
}
]

Get Sessions​

Retrieves the sessions stored into Smocker. For each session, it will contains its ID, its name, the mocks declared and the history of the calls made during this one.

  • Endpoint: GET /sessions
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Sample Response:
[
{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "",
"date": "2020-02-12T00:04:29.5940297+01:00",
"history": [
{
"mock_id": "05519745-7648-46ed-a5b0-757534e077d0",
"request": {
"path": "/hello/world",
"method": "GET",
"body": "",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"date": "2020-02-12T00:04:46.1526269+01:00"
},
"response": {
"status": 200,
"body": {
"message": "Hello, World!"
},
"headers": {
"Content-Type": ["application/json"]
},
"date": "2020-02-12T00:04:46.1532019+01:00"
}
},
{
"mock_id": "f6634848-f32f-4b89-93eb-8a3a37809350",
"request": {
"path": "/hello/world",
"method": "POST",
"body": "",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Content-Length": ["0"],
"Content-Type": ["application/x-www-form-urlencoded"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"date": "2020-02-12T00:04:46.1552296+01:00"
},
"response": {
"status": 500,
"body": {
"message": "error"
},
"headers": {
"Content-Type": ["application/json"]
},
"date": "2020-02-12T00:04:46.155561+01:00"
}
},
{
"request": {
"path": "/hello/world",
"method": "DELETE",
"body": "",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"date": "2020-02-12T00:04:48.3166388+01:00"
},
"response": {
"status": 666,
"body": {
"message": "No mock found matching the request",
"request": {
"body": "",
"date": "2020-02-12T00:04:48.3166459+01:00",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"method": "DELETE",
"path": "/hello/world"
}
},
"headers": {
"Content-Type": ["application/json; charset=UTF-8"]
},
"date": "2020-02-12T00:04:48.3172842+01:00"
}
}
],
"mocks": [
{
"request": {
"path": "/hello/world",
"method": "POST"
},
"response": {
"body": "{\"message\": \"error\"}\n",
"status": 500,
"headers": {
"Content-Type": ["application/json"]
}
},
"context": {},
"state": {
"id": "f6634848-f32f-4b89-93eb-8a3a37809350",
"times_count": 1,
"creation_date": "2020-02-12T00:04:43.3337512+01:00"
}
},
{
"request": {
"path": "/hello/world",
"method": "GET"
},
"response": {
"body": "{\"message\": \"Hello, World!\"}\n",
"status": 200,
"headers": {
"Content-Type": ["application/json"]
}
},
"context": {},
"state": {
"id": "05519745-7648-46ed-a5b0-757534e077d0",
"times_count": 1,
"creation_date": "2020-02-12T00:04:43.3337425+01:00"
}
}
]
}
]

Get Sessions Summary​

Retrieves a summary of the sessions stored into Smocker. For each session, it will only contains the ID and the name of this one.

  • Endpoint: GET /sessions/summary
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Sample Response:
[
{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "test1",
"date": "2020-02-12T00:04:43.3337425+01:00"
},
{
"id": "c1ac51b0-2a66-4b26-bffe-fac019cd734f",
"name": "test2",
"date": "2020-02-12T00:14:43.3337425+01:00"
}
]

Start Session​

Starts a new session into Smocker, and returns its summary.

  • Endpoint: POST /sessions
  • Query Parameters:
NameDescription
nameOptional, the name of the new session to start.
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Sample Response:
{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "test1"
}

Update Session​

Updates a session's name.

  • Endpoint: PUT /sessions
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 404 Not Found, if no session match the ID passed in parameter.
    • 500 Internal Server Error, if an error occurs during the session update.
  • Sample Body:

{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "test"
}
  • Sample Response:
{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "test",
"date": "2020-02-12T00:04:43.3337425+01:00"
}

Verify Session​

Verifies that for a session (by default the last one) the mocks have been called the right number of times according their context and that there is no Smocker error in history.

  • Endpoint: POST /sessions/verify
  • Query Parameters:
NameDescription
sessionOptional, the ID of the session to which the mock(s) belong. (default: last session ID)
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 404 Not Found, if no session match the ID passed in parameter.
  • Sample Response:

{
"mocks": {
"verified": true,
"all_used": true,
"message": "All mocks match expectations"
},
"history": {
"verified": true,
"message": "History is clean"
}
}
  • Sample Response:
{
"mocks": {
"verified": false,
"all_used": false,
"message": "Some mocks don't match expectations",
"failures": [
{
"request": {
"path": "/test",
"method": "GET"
},
"response": {
"body": "{\"message\": \"test2\"}\n",
"status": 200,
"headers": {
"Content-Type": ["application/json"]
}
},
"context": {
"times": 1
},
"state": {
"id": "6ecbd8f8-e2a7-4119-9be6-ad5ec83c58b6",
"times_count": 2,
"creation_date": "2020-02-26T12:11:34.713399+01:00"
}
},
{
"request": {
"path": "/test",
"method": "GET"
},
"response": {
"body": "{\"message\": \"test\"}\n",
"status": 200,
"headers": {
"Content-Type": ["application/json"]
}
},
"context": {
"times": 1
},
"state": {
"id": "30266b21-77c0-48e6-b27e-5aa02d7defd8",
"times_count": 2,
"creation_date": "2020-02-26T12:11:34.713396+01:00"
}
}
],
"unused": [
{
"request": {
"path": "/test",
"method": "GET"
},
"response": {
"status": 200
},
"context": {},
"state": {
"id": "d9ce47d4-86b7-4cb5-b7e9-829063704cec",
"times_count": 0,
"creation_date": "2020-02-26T12:11:34.747289+01:00"
}
}
]
},
"history": {
"verified": false,
"message": "There are errors in the history",
"failures": [
{
"request": {
"path": "/test",
"method": "GET",
"body": "",
"headers": {
"Accept-Encoding": ["gzip"],
"Host": ["localhost:8080"],
"User-Agent": ["Go-http-client/1.1"]
},
"date": "2020-02-26T12:11:34.737809+01:00"
},
"response": {
"status": 666,
"body": {
"message": "Matching mock found but was exceeded",
"nearest": [
{
"context": {
"times": 1
},
"request": {
"method": "GET",
"path": "/test"
},
"response": {
"body": "{\"message\": \"test2\"}\n",
"headers": {
"Content-Type": ["application/json"]
},
"status": 200
},
"state": {
"creation_date": "2020-02-26T12:11:34.713399+01:00",
"id": "6ecbd8f8-e2a7-4119-9be6-ad5ec83c58b6",
"times_count": 2
}
},
{
"context": {
"times": 1
},
"request": {
"method": "GET",
"path": "/test"
},
"response": {
"body": "{\"message\": \"test\"}\n",
"headers": {
"Content-Type": ["application/json"]
},
"status": 200
},
"state": {
"creation_date": "2020-02-26T12:11:34.713396+01:00",
"id": "30266b21-77c0-48e6-b27e-5aa02d7defd8",
"times_count": 2
}
}
],
"request": {
"body": "",
"date": "2020-02-26T12:11:34.737814+01:00",
"headers": {
"Accept-Encoding": ["gzip"],
"Host": ["localhost:8080"],
"User-Agent": ["Go-http-client/1.1"]
},
"method": "GET",
"path": "/test"
}
},
"headers": {
"Content-Type": ["application/json; charset=UTF-8"]
},
"date": "2020-02-26T12:11:34.738625+01:00"
}
}
]
}
}

Import Sessions​

Allows you to import a list of sessions fetched from another Smocker instance. It should be useful for analyzing into your local instance, the sessions generated during a CI execution.

  • Endpoint: POST /sessions/import
  • Headers:
NameValuesDescription
Acceptapplication/json, application/x-yamlOptional (defaults to application/json), the preferred mime type of the response.
  • Errors:

    • 400 Bad Request, if sessions are invalid.
  • Sample Body:

[
{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "test",
"date": "2020-02-12T00:04:29.5940297+01:00",
"history": [
{
"mock_id": "05519745-7648-46ed-a5b0-757534e077d0",
"request": {
"path": "/hello/world",
"method": "GET",
"body": "",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"date": "2020-02-12T00:04:46.1526269+01:00"
},
"response": {
"status": 200,
"body": {
"message": "Hello, World!"
},
"headers": {
"Content-Type": ["application/json"]
},
"date": "2020-02-12T00:04:46.1532019+01:00"
}
},
{
"mock_id": "f6634848-f32f-4b89-93eb-8a3a37809350",
"request": {
"path": "/hello/world",
"method": "POST",
"body": "",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Content-Length": ["0"],
"Content-Type": ["application/x-www-form-urlencoded"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"date": "2020-02-12T00:04:46.1552296+01:00"
},
"response": {
"status": 500,
"body": {
"message": "error"
},
"headers": {
"Content-Type": ["application/json"]
},
"date": "2020-02-12T00:04:46.155561+01:00"
}
},
{
"request": {
"path": "/hello/world",
"method": "DELETE",
"body": "",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"date": "2020-02-12T00:04:48.3166388+01:00"
},
"response": {
"status": 666,
"body": {
"message": "No mock found matching the request",
"request": {
"body": "",
"date": "2020-02-12T00:04:48.3166459+01:00",
"headers": {
"Accept": ["application/json, text/plain, */*"],
"Connection": ["close"],
"Host": ["localhost:8080"],
"User-Agent": ["axios/0.19.2"]
},
"method": "DELETE",
"path": "/hello/world"
}
},
"headers": {
"Content-Type": ["application/json; charset=UTF-8"]
},
"date": "2020-02-12T00:04:48.3172842+01:00"
}
}
],
"mocks": [
{
"request": {
"path": "/hello/world",
"method": "POST"
},
"response": {
"body": "{\"message\": \"error\"}\n",
"status": 500,
"headers": {
"Content-Type": ["application/json"]
}
},
"context": {},
"state": {
"id": "f6634848-f32f-4b89-93eb-8a3a37809350",
"times_count": 1,
"creation_date": "2020-02-12T00:04:43.3337512+01:00"
}
},
{
"request": {
"path": "/hello/world",
"method": "GET"
},
"response": {
"body": "{\"message\": \"Hello, World!\"}\n",
"status": 200,
"headers": {
"Content-Type": ["application/json"]
}
},
"context": {},
"state": {
"id": "05519745-7648-46ed-a5b0-757534e077d0",
"times_count": 1,
"creation_date": "2020-02-12T00:04:43.3337425+01:00"
}
}
]
}
]
  • Sample Response:
[
{
"id": "1d6d264b-4d13-4e0b-a51e-e44fc80eca9f",
"name": "test",
"date": "2020-02-12T00:04:29.5940297+01:00"
}
]

Healthcheck​

Check that Smocker is up and running. The version data of the currently deployed instance are also returned.

  • Endpoint: GET /version
  • Sample Response:
{
"app_name": "smocker",
"build_version": "0.4.0",
"build_commit": "b12ba66b13b9719b29afc58e6f1953367b78ecfd",
"build_date": "2019-11-27T10:38:53+0000"
}