feat(fleetbase-api): driver manifests and driver password endpoints - #53
Merged
Merged
Conversation
Documents the consumable endpoints added in fleetops#304 and fleetops#305. Drivers gains three password requests. A password change is an authorisation decision rather than an attribute update, which is why it is not part of PUT /drivers/:id — that endpoint no longer accepts a password at all. The descriptions carry the two properties a caller needs to know about and cannot discover by trying: the reset request answers identically whether or not the identity exists, so it cannot be used to enumerate an organization's drivers, and a wrong code, an expired code and an unknown identity all return the same error. A new Manifests folder covers the route a driver actually drives — a manifest is an order-agnostic sequence of stops which may span several orders, or none the driver has seen as an order. Retrieve returns the stops in sequence with their places inline, so a route of twenty stops is one request rather than twenty-one. The optimize description says plainly what it is: a nearest-neighbour walk over road distances, usually a large improvement on an arbitrary order and not guaranteed optimal, which reorders the stops of one assigned manifest rather than allocating work across a fleet the way the orchestrator does. Completed and skipped stops keep their place. Listing a driver's manifests sits with the other driver-scoped requests rather than in the new folder, next to List Driver Organizations. No response examples yet: the endpoints are still in review on the fleetops release branch, and an example recorded against an unmerged branch would be a guess rather than verified behaviour. Happy to add them once merged. npm run postman:lint — 196 requests scanned in Fleetbase API, 0 errors, 0 warnings.
The collection asserts every request returns 2xx, so a request that cannot succeed unattended reads as a broken endpoint. - Create a Driver seeds a known password and captures the generated email and phone. They are generated inline, so the response is the only place to read them back, and without them the password requests had no identity and no current password to prove. - The password and manifest requests run before Delete a Driver rather than after it. At 13000 they addressed a driver deleted at 5000. - Reset Driver Password skips itself: its code arrives by email or SMS, which an automated run cannot read. - Request Driver Password Reset addresses a reserved address that belongs to nobody. The endpoint answers identically for an unknown identity, so it is still exercised and no stranger is sent a code. - The manifest requests skip themselves when the run found no manifest.
This was referenced Aug 31, 2026
Member
Author
|
The follow-up for the FleetOps contract failures this introduced is #57 — this branch's later pushes landed after the merge, so they were not part of what shipped here. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the consumable endpoints added in
fleetops#304 and
fleetops#305.
Drivers — password management
POST /drivers/:id/change-passwordPOST /drivers/forgot-passwordPOST /drivers/reset-passwordA password change is an authorisation decision rather than an attribute update,
which is why it is not part of
PUT /drivers/:id— that endpoint no longeraccepts a password at all, which is the security fix in fleetops#304.
The descriptions carry the two properties a caller needs to know and cannot
discover by trying:
so it cannot be used to enumerate an organization's drivers
error, so reset is not an oracle either
Manifests — a new folder
GET /drivers/:id/manifestsGET /manifests/:idPATCH /manifest-stops/:idPOST /manifests/:id/optimizeA manifest is a driver's route: an order-agnostic sequence of stops which may
span several orders, or none the driver has seen as an order. Retrieve returns
the stops in sequence with their places inline, so a route of twenty stops is
one request rather than twenty-one.
The
optimizedescription says plainly what it is — a nearest-neighbour walkover road distances, usually a large improvement on an arbitrary order and not
guaranteed optimal. It reorders the stops of one assigned manifest rather than
allocating work across a fleet, which is what the orchestrator does. Completed
and skipped stops keep their place.
Creating, cancelling and deleting a manifest are dispatch operations and are
deliberately absent — they are not part of the consumable API.
Listing a driver's manifests sits with the other driver-scoped requests rather
than in the new folder, next to List Driver Organizations.
Validation
Not included: response examples
The endpoints are still in review on the fleetops release branch. An example
recorded against an unmerged branch would be a guess rather than verified
behaviour, and this repo's own rules ask for spec updates backed by verified
API behaviour. Happy to add them in a follow-up once fleetops#304 and #305 merge
— say the word and I will capture real responses against
dev-v0.6.61.Merge order
driver_password_resetcode this collection needs.fleetbase/fleetops#304 and #305 are already merged to
dev-v0.6.61, so the endpoints themselves exist.Running unattended
The collection asserts that every request returns 2xx, so a request that cannot succeed on its own
reads as a broken endpoint rather than as an untestable one.
created_driver_*. It deliberately does not writedriver_identity,driver_passwordordriver_phone: those name the driver a contract run seeds and injects, and Login Driver, RequestDriver Login SMS and Verify Driver Login Code authenticate as it. Writing the throwaway driver's
details there signed all three in as an account deleted a few requests earlier.
POST /orchestrator/commitis whatcreates a manifest — it returns the ids it created, and that is where the folder gets one. Retrieve
a Manifest then passes a stop id to Update a Manifest Stop.
endpoint matches on purpose as well as on value — and sets the password back to the one already in
force, so the run stays repeatable and the login requests below still authenticate.
The endpoint answers identically for an unknown identity — deliberately, so it cannot enumerate
drivers — so it is still exercised and no stranger receives a reset code.
pm.execution.skipRequest()is not a skipAn earlier revision guarded the requests that need a fixture with
pm.execution.skipRequest(). ThePostman CLI reports that as "Request could not be completed" — a run error, which fails the
contract exactly as a bad response would. Every guard is gone; each request now has something real to
address instead.
Verified
npm run postman:lintis clean (196 requests, 0 errors, 0 warnings).POST /drivers/{id}/change-passwordand
GET /drivers/{id}/manifestswere both confirmed 200 against a live instance running the mergeddev-v0.6.61.Response examples still to add.