Integration readiness teardown

fulfilment-api.json

Sealed report: b5e639b6b714
Profile: default v1
Engine: 0.1.0
Coverage: complete
Read: 1082 fragments

At a glance

findings

causes (one piece of work each)

points taken off

critical or high findings

Critical	High	Medium	Low
0	0	49	23

Rules: 11 found a gap, 13 found none, 11 not applicable, 4 could not be assessed, 2 switched off, 0 failed. The weakest family is contract. 162 points were not taken because a rule reached its cap.

Fix first

Clearing these 5 causes takes back 47 points of 57 points (82.5%).

#	Severity	Rule	Cause	Places	Points	Running total
1	medium	`CC-PARAM-01`	required parameter without description	42	15	15
2	medium	`PAG-01`	no pagination	5	15	30
3	low	`CC-DESC-02`	weak description: restates its name	9	9	39
4	low	`CC-RESP-01`	response without description	4	4	43
5	medium	`CC-EX-02`	example violates schema at /absolutemoneycost	1	4	47

Families

Family	Sub-score	Findings	Causes	Points	Share	Rules: applied · clean · not assessed	Worst rules (findings)
contract	68	60	7	32	56.1%	14 · 10 · 1	`CC-PARAM-01 (43), CC-DESC-02 (11), CC-RESP-01 (4), NAME-01 (2)`
pagination	85	5	1	15	26.3%	1 · 0 · 0	`PAG-01 (5)`
examples	95	2	2	5	8.8%	2 · 0 · 0	`CC-EX-02 (1), CC-EX-01 (1)`
onboarding	98	2	1	2	3.5%	2 · 1 · 1	`AUTH-02 (2)`
data	99	1	1	1	1.8%	1 · 0 · 0	`DATA-02 (1)`
limits	99	1	1	1	1.8%	1 · 0 · 0	`RATE-01 (1)`
reliability	99	1	1	1	1.8%	1 · 0 · 0	`IDEM-01 (1)`
errors	100	0	0	0	0%	2 · 2 · 0

No rule applied, so nothing was assessed for: documentation, lifecycle, links, webhooks, workflow. That is not a clean result.

Hotspots

40 operations with findings. 8 findings are about the document as a whole (11 points).

Operations

Operation	Points	Findings	Med.	Low	Families	Rules
`GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values`	6	3	1	2	contract, pagination	`CC-DESC-02, PAG-01`
`GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}`	4	2	1	1	contract	`CC-PARAM-01, CC-RESP-01`
`DELETE /api/fulfilment/v1/configuration/holidays/{holidayId}`	4	1	1	0	contract	`CC-PARAM-01`
`DELETE /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}`	4	1	1	0	contract	`CC-PARAM-01`
`GET /api/fulfilment/v1/configuration/docks`	4	1	1	0	pagination	`PAG-01`
`GET /api/fulfilment/v1/configuration/warehouses`	4	1	1	0	pagination	`PAG-01`
`GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}`	4	1	1	0	contract	`CC-PARAM-01`
`GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched`	3	3	3	0	contract, pagination	`CC-PARAM-01, PAG-01`
`PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId}`	1	3	2	1	contract	`CC-DESC-02, CC-PARAM-01`
`GET /api/fulfilment/v1/inventory/skus/{skuId}`	1	2	1	1	contract	`CC-PARAM-01, CC-RESP-01`
`POST /api/fulfilment/v1/configuration/docks/{dockId}/activation`	1	2	1	1	contract	`CC-DESC-02, CC-PARAM-01`
`POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation`	1	2	1	1	contract	`CC-DESC-02, CC-PARAM-01`
`POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/activation`	1	2	1	1	contract	`CC-DESC-02, CC-PARAM-01`
`POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/deactivation`	1	2	1	1	contract	`CC-DESC-02, CC-PARAM-01`
`POST /api/fulfilment/v1/inventory/reservations/{reservationId}/acknowledge`	1	2	1	1	contract	`CC-DESC-02, CC-PARAM-01`

Resources

Resource	Points	Findings	Crit.	High	Med.	Low	Families	Rules
`/api` (40 operations)	46	64	0	0	48	16	contract, examples, pagination	`CC-DESC-02, CC-EX-01, CC-PARAM-01, CC-RESP-01, PAG-01`

What this report cannot say

Source	Provides	Coverage	Read	Not read	Failed
`fulfilment-api.json`	an API description	complete	1	0	0

4 checks could not be made: needs guide pages; none was supplied. Not a pass, and no points were taken off. CC-CONFLICT-01, LINK-01, ON-ENV-01, DOC-CODE-01
1 rule reported findings, but 1 example was not checked against its schema: the example is too long to keep. There may be more. CC-EX-02
2 rules are switched off by the profile. PAG-02, CC-DESC-03

Since the earlier review

Compared with sealed report 22aca6e881d8: 1 new, 71 persistent, 56 resolved, 0 changed, 0 not shown to be fixed.

Causes in detail

medium `CC-PARAM-01` required parameter without description

contract · 42 places · 15 points taken, 153 points withheld by the rule's cap

Impact. Developers must guess the meaning, format and valid values of a parameter they are required to send.

Recommendation. Describe what the parameter means, its format and valid values.

Where. GET /api/fulfilment/v1/configuration/warehouses/{warehouseId}, DELETE /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, DELETE /api/fulfilment/v1/configuration/holidays/{holidayId}, GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, GET /api/fulfilment/v1/configuration/pickuppoints/_search, GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}/warehouses/{warehouseId}, GET /api/fulfilment/v1/inventory/items/{skuId}/docks/{dockId}, GET /api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId} and 24 more

Evidence, first place. not found: description; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses~1{warehouseId}/get/parameters/2

medium `PAG-01` no pagination

pagination · 5 places · 15 points taken, 5 points withheld by the rule's cap

Impact. Clients cannot retrieve more than the first batch reliably, or must guess how paging works.

Recommendation. Document a pagination mechanism (cursor or page parameters and the field or header carrying the next position).

Where. GET /api/fulfilment/v1/configuration/warehouses, GET /api/fulfilment/v1/configuration/docks, GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values, GET /api/fulfilment/v1/inventory/items/{itemId}/warehouses/{warehouseId}/dispatched, GET /api/fulfilment/v1/configuration/pickuppoints

Evidence, first place. not found: pagination parameters, next-page field or Link header; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/get, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/get/responses/200, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/get/responses/default

low `CC-DESC-02` weak description: restates its name

contract · 9 places · 9 points taken

Impact. A description that says nothing beyond the name gives a developer no more than the name already did.

Recommendation. Say what it does, what it returns or accepts, and anything the name does not show.

Where. POST /api/fulfilment/v1/inventory/reservations/{reservationId}/confirm, POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/activation, PUT /api/fulfilment/v1/configuration/holidays/{holidayId}, POST /api/fulfilment/v1/configuration/warehouses/{warehouseId}/deactivation, POST /api/fulfilment/v1/inventory/reservations/{reservationId}/acknowledge, POST /api/fulfilment/v1/inventory/reservations/{reservationId}/cancel, POST /api/fulfilment/v1/configuration/docks/{dockId}/deactivation, PUT /api/fulfilment/v1/inventory/skus/{skuId}/warehouses/{warehouseId} and 1 more

Evidence, first place. "Confirms reservation by reservation ID." at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1reservations~1{reservationId}~1confirm/post

low `CC-RESP-01` response without description

contract · 4 places · 4 points taken

Impact. Developers do not learn what the response means or when it occurs.

Recommendation. Describe when this response is returned and what it contains.

Where. PUT /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, GET /api/fulfilment/v1/inventory/skus/{skuId}, GET /api/fulfilment/v1/configuration/pickuppoints/{pickupPointId}, POST /api/fulfilment/v1/shipping/calculate

Evidence, first place. not found: description; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1pickuppoints~1{pickupPointId}/put/responses/200

medium `CC-EX-02` example violates schema at /absolutemoneycost

examples · 1 place · 4 points taken

Impact. The example breaks an explicit constraint declared in the schema (not one inferred from prose), so a developer who copies it gets a request the API rejects, or a response shape the schema does not promise.

Recommendation. Correct the example or the schema so they agree.

Where. Example does not match its schema at `/absoluteMoneyCost`: "1.00" is not of type "number"

Evidence. "{"absoluteMoneyCost":"1.00","country":"XYZ","maxVolume":1000000000,"operationType":1,"polygon":"","pricePercent":0,"pricePercentByWeight":0,"timeCost":"2.00:00:00","weightEnd":1000,"weightStart":1,"zipCodeEnd":"99999999","zipCodeStart":"0"}" at fulfilment-api.json#/components/schemas/CreateUpdateFreightValuesRequest/example

low `AUTH-02` security scheme without description

onboarding · 2 places · 2 points taken

Impact. Developers are not told how to obtain or send credentials for this scheme.

Recommendation. Describe how to obtain credentials and how to send them.

Where. Security scheme `appToken` has no description, Security scheme `appKey` has no description

Evidence, first place. not found: description; inspected fulfilment-api.json#/components/securitySchemes/appToken

low `CC-DESC-02` weak description: too short

contract · 2 places · 2 points taken

Impact. A description that says nothing beyond the name gives a developer no more than the name already did.

Recommendation. Say what it does, what it returns or accepts, and anything the name does not show.

Where. GET /api/fulfilment/v1/configuration/freights/{carrierId}/{postalCode}/values

Evidence, first place. "Postal code." at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1freights~1{carrierId}~1{postalCode}~1values/get/parameters/3

low `CC-EX-01` no request or response example

examples · 1 place · 1 point taken

Impact. Developers have to infer payload shape from the schema alone, which slows a first successful call.

Recommendation. Add a realistic example for the request body and the success response.

Where. PUT /api/fulfilment/v1/configuration/geoshape

Evidence. not found: an example request or response body; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1geoshape/put, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1geoshape/put/responses/200

low `DATA-02` unformatted date/time properties

data · 1 place · 1 point taken

Impact. Clients cannot tell whether values are ISO 8601, epoch text or local time, so parsing and timezone handling are guesses.

Recommendation. Set `format: date-time` or `date`, or describe the format and timezone (for example ISO 8601 in UTC).

Where. 25 date/time-named string properties declare no format or timezone

Evidence. "closingTime" at fulfilment-api.json#/components/schemas/BusinessHour/properties

Evidence. "openingTime" at fulfilment-api.json#/components/schemas/BusinessHour/properties

Evidence. "startDate" at fulfilment-api.json#/components/schemas/CreateUpdateHolidayRequest/properties

Evidence. "dockTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "timeToDockPlusDockTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "totalTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "transitTime" at fulfilment-api.json#/components/schemas/DeliveryItemOption/properties

Evidence. "endTime" at fulfilment-api.json#/components/schemas/DeliveryRange/properties

Evidence. "startTime" at fulfilment-api.json#/components/schemas/DeliveryRange/properties

Evidence. "endTime" at fulfilment-api.json#/components/schemas/DeliveryRange1/properties

low `IDEM-01` no idempotency

reliability · 1 place · 1 point taken

Impact. A retry after a timeout can create the resource twice, so clients cannot retry safely.

Recommendation. Accept an Idempotency-Key header on creating operations and document how long keys are remembered.

Where. None of the 4 resource-creating POST operations documents an idempotency key

Evidence. not found: an Idempotency-Key header parameter; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1docks/post, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1warehouses/post, fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1reservations/post and 1 more

low `NAME-01` verbs in some paths

contract · 1 place · 1 point taken

Impact. Action verbs in some resource paths duplicate what the HTTP method already says and break the pattern of the other paths.

Recommendation. Name paths after resources and express the action with the HTTP method.

Where. 1 of 40 paths put an action verb in the path while the rest do not

Evidence. "/api/fulfilment/v1/configuration/freights/{carrierId}/values/update" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1freights~1{carrierId}~1values~1update/post

low `NAME-01` inconsistent casing: kebab-case,snake_case,camelcase

contract · 1 place · 1 point taken

Impact. Inconsistent naming makes the API harder to learn and guess; developers cannot predict names from the ones they have seen.

Recommendation. Choose one naming convention and apply it everywhere; keep old names only as documented deprecated aliases.

Where. paths mix kebab-case, snake_case, camelCase with no dominant convention

Evidence. "/api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames" at fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames/get

Evidence. "/api/fulfilment/v1/configuration/pickuppoints/_search" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1configuration~1pickuppoints~1_search/get

Evidence. "/api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1items~1{skuId}~1warehouses~1{warehouseId}~1supplyLots/get

Evidence. "/api/fulfilment-capacity/resources/carrier@{capacityType}@{shippingPolicyId}/time-frames/{windowDay}F{windowStartTime}T{windowEndTime}" at fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime}T{windowEndTime}/get

Evidence. "/api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1items~1{skuId}~1warehouses~1{warehouseId}~1supplyLots~1{supplyLotId}/put

Evidence. "/api/fulfilment/v1/inventory/items/{skuId}/warehouses/{warehouseId}/supplyLots/{supplyLotId}/transfer" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1inventory~1items~1{skuId}~1warehouses~1{warehouseId}~1supplyLots~1{supplyLotId}~1transfer/post

Evidence. "/api/fulfilment/v1/shipping-policies" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1shipping-policies/get

Evidence. "/api/fulfilment/v1/shipping-policies/{id}" at fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1shipping-policies~1{id}/get

low `RATE-01` no rate limit documentation

limits · 1 place · 1 point taken

Impact. Integrators cannot size their clients or plan back-off, and learn the limits from production errors.

Recommendation. Document the limits, a 429 response and the headers that report remaining quota and when to retry.

Where. No rate limiting is documented

Evidence. not found: a 429 response, rate-limit headers, or a description of rate limits; inspected fulfilment-api.json#, fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames/get, fulfilment-api.json#/paths/~1api~1fulfilment-capacity~1resources~1carrier@{capacityType}@{shippingPolicyId}~1time-frames~1{windowDay}F{windowStartTime}T{windowEndTime}/get and 3 more

medium `CC-PARAM-01` required request property without description

contract · 1 place · 0 points taken, 4 points withheld by the rule's cap

Impact. Developers must guess the meaning, format and valid values of a field they are required to send.

Recommendation. Describe what the property means, its format and valid values.

Where. POST /api/fulfilment/v1/shipping-policies

Evidence. not found: description; inspected fulfilment-api.json#/paths/~1api~1fulfilment~1v1~1shipping-policies/post/requestBody/content/application~1json/schema/properties/cubicWeightSettings/properties/minimunAcceptableVolumetricWeight

Every rule

Rule	Family	Version	Result	Findings
`CC-REF-01`	contract	1	no gap found	0
`CC-DESC-01`	contract	1	no gap found	0
`CC-PARAM-01`	contract	1	gap found	43
`CC-RESP-01`	contract	1	gap found	4
`CC-ERR-01`	contract	1	no gap found	0
`CC-EX-01`	examples	1	gap found	1
`CC-EX-02`	examples	1	gap found	1
`ERR-05`	errors	1	not applicable	0
`CC-CONFLICT-01`	contract	1	could not be assessed (needs guide pages; none was supplied)	0
`CC-PATH-01`	contract	1	no gap found	0
`CC-SCHEMA-01`	contract	1	no gap found	0
`CC-TYPE-01`	contract	1	no gap found	0
`CC-CONSIST-01`	contract	1	no gap found	0
`RATE-02`	limits	1	not applicable	0
`WH-01`	webhooks	1	not applicable	0
`WH-02`	webhooks	1	not applicable	0
`WH-03`	webhooks	1	not applicable	0
`AUTH-03`	onboarding	1	not applicable	0
`IDEM-02`	reliability	1	not applicable	0
`ERR-04`	errors	1	no gap found	0
`WF-04`	workflow	1	not applicable	0
`DATA-02`	data	1	gap found	1
`DATA-03`	data	1	not applicable	0
`CC-ENV-01`	contract	1	no gap found	0
`AUTH-04`	onboarding	1	not applicable	0
`AUTH-01`	onboarding	1	no gap found	0
`AUTH-02`	onboarding	1	gap found	2
`CC-SEC-01`	contract	1	no gap found	0
`NAME-01`	contract	1	gap found	2
`PAG-01`	pagination	1	gap found	5
`PAG-02`	pagination	1	switched off	0
`RATE-01`	limits	1	gap found	1
`ERR-02`	errors	1	no gap found	0
`IDEM-01`	reliability	1	gap found	1
`CC-DEP-01`	lifecycle	1	not applicable	0
`CC-DESC-02`	contract	1	gap found	11
`CC-DESC-03`	contract	1	switched off	0
`CC-DESC-04`	contract	1	no gap found	0
`LINK-01`	links	1	could not be assessed (needs guide pages; none was supplied)	0
`ON-ENV-01`	onboarding	1	could not be assessed (needs guide pages; none was supplied)	0
`DOC-CODE-01`	documentation	1	could not be assessed (needs guide pages; none was supplied)	0

Method

Every figure is a count, a sum or a sort over the sealed report. Nothing was estimated or generated.
Points are the deductions the profile applies to findings, as recorded in the report's score trace. They rank findings; they are not a measure of how long a fix takes.
A cause is the findings of one rule that share one problem at different places; it counts as one piece of work. Causes are ranked by points taken, then by places, then by severity, then by rule id.
A resource is the first path segment of an operation. A finding with no operation is about the document as a whole and is counted apart.
The detail part shows at most 8 places per cause and the evidence of its first finding. The JSON report and the SARIF export carry every finding.
A rule that could not be assessed is neither a pass nor a deduction. A rule that found nothing while an input it needs was read only in part is not a clean result.
Confidence values in the report are a rule's own estimate, not a calibrated probability, and are not used for any figure here.

Integration readiness teardown

At a glance

Fix first

Families

Hotspots

Operations

Resources

What this report cannot say

Since the earlier review

Causes in detail

medium CC-PARAM-01 required parameter without description

medium PAG-01 no pagination

low CC-DESC-02 weak description: restates its name

low CC-RESP-01 response without description

medium CC-EX-02 example violates schema at /absolutemoneycost

low AUTH-02 security scheme without description

low CC-DESC-02 weak description: too short

low CC-EX-01 no request or response example

low DATA-02 unformatted date/time properties

low IDEM-01 no idempotency

low NAME-01 verbs in some paths

low NAME-01 inconsistent casing: kebab-case,snake_case,camelcase

low RATE-01 no rate limit documentation

medium CC-PARAM-01 required request property without description