From 2ee3ff6f6231f3b8a2a5850352240ec1e648045e Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:06:26 -0500 Subject: [PATCH 01/12] Update readme.md --- readme.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/readme.md b/readme.md index 5eff1f7..8ba76d6 100644 --- a/readme.md +++ b/readme.md @@ -9,15 +9,18 @@ To learn more about FSMB APIs, refer to the [Getting Started](https://github.com - URL - Demo: https://services-fcvs-demo.fsmb.org - Production: https://services-fcvs.fsmb.org +- Authentication URL `/connect/token` - [Postman Collection](https://www.getpostman.com/collections/b59f8de00ca54eb654b7) - [OpenAPI Specification](https://services-fcvs.fsmb.org/swagger/v1) -[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/b59f8de00ca54eb654b7) +[Run In Postman](https://app.getpostman.com/run-collection/1384052-bbfef0d8-d867-446d-8ae8-08d42b035ebe?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D1384052-bbfef0d8-d867-446d-8ae8-08d42b035ebe%26entityType%3Dcollection%26workspaceId%3D58240218-129c-4c2c-a71a-139a2efabdb2#?env%5BFCVS%20(Demo)%5D=W3siZW5hYmxlZCI6dHJ1ZSwia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9zZXJ2aWNlcy1mY3ZzLWRlbW8uZnNtYi5vcmcifSx7ImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJrZXkiOiJjbGllbnRJZCIsInZhbHVlIjoiRE9fTk9UX1NFVCJ9LHsiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsImtleSI6ImNsaWVudFNlY3JldCIsInZhbHVlIjoiRE9fTk9UX1NFVCJ9XQ==) + ## Change Log -| Version | Date | Release Notes | -| - | - | -| -| 1.0 | 5 Dec 2019 | Initial version | +| Date | Release Notes | +| - | -| +| Aug 2026 | [Release Notes](relnotes/relnotes-202608.md) | +| Dec 2019 | Initial version | ## Security From dca28cd970faf81646062f822d189765ed52556a Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:07:07 -0500 Subject: [PATCH 02/12] Create relnotes-202608.md --- relnotes/relnotes-202608.md | 42 +++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 relnotes/relnotes-202608.md diff --git a/relnotes/relnotes-202608.md b/relnotes/relnotes-202608.md new file mode 100644 index 0000000..327bbcf --- /dev/null +++ b/relnotes/relnotes-202608.md @@ -0,0 +1,42 @@ +# Release August 2026 + +## What's New + +- [Singular Names](#singular-names) +- [Error Reporting](#error-reporting) + +## Breaking Changes +The format for reporting errors has changed to align with standard API practices. Refer to [Error Reporting](#error-reporting) for more information. + +## Singular Names + +Support for singular names has been added to the API for physician names. Physicians who have only a last name are considered to have a singular name. +To support this the following changes have been made to the physician's [Name](docs/definitions/name.md). + +- The `firstName` field is still required. If the physician has a singular name then the field is set to `FNU` which indicates there is no first name. +- A `isSingularName` field has been added to indicate when the name is singular. + +Existing clients will continue to behave as before but should consider updating to support singular names. + +- If `isSingularName` is set then the `firstName` should be considered empty and not the value specified. +- It is possible that a physician's first name is `FNU`. Therefore clients should not assume that a first name set to this value is a singular name. Use the indicator instead. + +## Error Reporting + +Historically errors from the API have returned an FSMB-specific error object containing the details of the error. The [RFC7807 Problem Details](https://tools.ietf.org/html/rfc7807) format has become the industry standard format for reporting errors and newer FSMB APIs use this format. Additionally some errors triggered by the lower level HTTP runtime would automatically return the `ProblemDetails` format before the API even had a chance to detect it. This causes confusion and requires that clients that need more detailed error information handle two different formats. + +To resolve this the API has fully transitioned to the `ProblemDetails` format for error reporting. This ensures consistent error reporting while also making it behave like other APIs. However this breaks any existing code that reads the error object for detailed information. To allow for migration the API returns additional fields as part of the standard `ProblemDetails` format that line up with some of the older fields. + +| Legacy Field | New Field | Description | +| - | - | - | +| `code` | `type` | Provides a unique identifier for the error | +| `message` | `detail` or `title` | Provides a friendly description of the error | +| `target` | `instance` | When applicable, the instance/field that the error is for | + +Clients should do the following: + +- Continue to use the HTTP status code for general error detection and reporting. +- If specific error details are needed, such as why a request was marked as bad, then read the `ProblemDetails` object. +- Any code relying on the older format including the legacy fields mentioned in the table should be migrated to use the new fields as soon as possible. + +The legacy fields will be removed in a future update. From 871b29029b69de3fe9803a36ba1f20a41da7c1ca Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:08:18 -0500 Subject: [PATCH 03/12] Added singular name fields --- docs/definitions/name.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/definitions/name.md b/docs/definitions/name.md index 09024ab..acea9a4 100644 --- a/docs/definitions/name.md +++ b/docs/definitions/name.md @@ -4,9 +4,10 @@ Name of a person | Name | Type | Required | Description | | - | - | - | - | -| firstName | string (len: 50) | Yes | First name | +| firstName | string (len: 50) | Yes | First name. If `isSingularName` is true then this field is set to `FNU`. | | middleName | string (len: 50) | No | Middle name | | lastName | string (len: 50) | Yes | Last name | | suffix | string (len: 4) | No | Suffix | +| isSingularName | boolean | Yes | Indicates if this is a singular name | *Note: Any fields marked as deprecated will be removed in a future version of the API. New code should not rely on these fields. Existing code should be updated to use alternative fields.* From 12c8c1d48ec1a766aaf669c69473fd490438354d Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:09:26 -0500 Subject: [PATCH 04/12] Update relnotes-202608.md --- relnotes/relnotes-202608.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/relnotes/relnotes-202608.md b/relnotes/relnotes-202608.md index 327bbcf..a757be9 100644 --- a/relnotes/relnotes-202608.md +++ b/relnotes/relnotes-202608.md @@ -11,7 +11,7 @@ The format for reporting errors has changed to align with standard API practices ## Singular Names Support for singular names has been added to the API for physician names. Physicians who have only a last name are considered to have a singular name. -To support this the following changes have been made to the physician's [Name](docs/definitions/name.md). +To support this the following changes have been made to the physician's [Name](/docs/definitions/name.md). - The `firstName` field is still required. If the physician has a singular name then the field is set to `FNU` which indicates there is no first name. - A `isSingularName` field has been added to indicate when the name is singular. From a3fde9b4ee4c7a87a0ab698e88b67800441466b2 Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 12:17:50 -0500 Subject: [PATCH 05/12] Update relnotes-202608.md --- relnotes/relnotes-202608.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/relnotes/relnotes-202608.md b/relnotes/relnotes-202608.md index a757be9..a9410c5 100644 --- a/relnotes/relnotes-202608.md +++ b/relnotes/relnotes-202608.md @@ -4,10 +4,13 @@ - [Singular Names](#singular-names) - [Error Reporting](#error-reporting) +- [Response Changes](#response-changes) ## Breaking Changes -The format for reporting errors has changed to align with standard API practices. Refer to [Error Reporting](#error-reporting) for more information. +- The format for reporting errors has changed to align with standard API practices. Refer to [Error Reporting](#error-reporting) for more information. +- Some endpoint responses have changed the status code returned to better reflect the error. Refer to [Response Changes](#response-changes) for more information. +- ## Singular Names Support for singular names has been added to the API for physician names. Physicians who have only a last name are considered to have a singular name. @@ -40,3 +43,10 @@ Clients should do the following: - Any code relying on the older format including the legacy fields mentioned in the table should be migrated to use the new fields as soon as possible. The legacy fields will be removed in a future update. + +## Response Changes + +Some endpoints have been adjusted to better reflect the data or error being returned. + +- Any endpoint accepting a FID now requires an exact 9-digit value. Previously less than 9 digits were allowed but would never be allowed. This resulted in no data being returned, e.g. 404 or 204. Now a 400 status is returned to reflect the invalid data. +- Previously passing an invalid board code to endpoint resulted in a 404. This was confusing since some endpoints return 404s when the request is valid but no data is available. Now passing a board code that is invalid will result in an 403 Forbidden error with a message indicating the code is invalid. From f25ced1456733c88515f3bcce222050048ddbd0e Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:38:05 -0500 Subject: [PATCH 06/12] Update get-current.md --- docs/practitioners-v1/get-current.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/practitioners-v1/get-current.md b/docs/practitioners-v1/get-current.md index ea13d13..e46ea56 100644 --- a/docs/practitioners-v1/get-current.md +++ b/docs/practitioners-v1/get-current.md @@ -1,6 +1,6 @@ -# Get Current +# Get Current Profile -Get the current FCVS Profile for a practitioner. +Gets the current FCVS Profile for a practitioner. ```http GET {baseUrl}/v1/boards/{board}/practitioners/{fid}/profiles/current @@ -19,7 +19,8 @@ GET {baseUrl}/v1/boards/{board}/practitioners/{fid}/profiles/current | Name | Type | Description | | - |-|-| | 200 OK | [Profile](/docs/definitions/profile.md) | Success | -| 404 Not Found | | Board code is missing/invalid or Practitioner does not have an FCVS Profile | +| 403 Forbidden | | Board code is invalid | +| 404 Not Found | | Profile not found | ## Security From 3fd25505628b0318595bb64964c123eb480b1b8d Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:57:16 -0500 Subject: [PATCH 07/12] Update get-status.md --- docs/practitioners-v1/get-status.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/practitioners-v1/get-status.md b/docs/practitioners-v1/get-status.md index 3431b8a..baef18c 100644 --- a/docs/practitioners-v1/get-status.md +++ b/docs/practitioners-v1/get-status.md @@ -19,7 +19,8 @@ GET {baseUrl}/v1/boards/{board}/practitioners/{fid}/status | Name | Type | Description | | - |-|-| | 200 OK | [Practitioner Status](/docs/definitions/practitioner-status.md) | Success | -| 404 Not Found | | Board code is missing/invalid or Practitioner does not have an FCVS Profile | +| 403 Forbidden | | Board code is invalid | +| 404 Not Found | | Profile not found | ## Security From f970341b2a7be6a41f4a168064b6e0783f572a9d Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Mon, 10 Aug 2026 14:57:46 -0500 Subject: [PATCH 08/12] Update relnotes-202608.md --- relnotes/relnotes-202608.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/relnotes/relnotes-202608.md b/relnotes/relnotes-202608.md index a9410c5..39d43f7 100644 --- a/relnotes/relnotes-202608.md +++ b/relnotes/relnotes-202608.md @@ -10,7 +10,7 @@ - The format for reporting errors has changed to align with standard API practices. Refer to [Error Reporting](#error-reporting) for more information. - Some endpoint responses have changed the status code returned to better reflect the error. Refer to [Response Changes](#response-changes) for more information. -- + ## Singular Names Support for singular names has been added to the API for physician names. Physicians who have only a last name are considered to have a singular name. From 0d2dbb5daa6cf978ba21eb73bcea7bb7ca40ff8e Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Wed, 12 Aug 2026 14:26:05 -0500 Subject: [PATCH 09/12] Updated to new openapi URL --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 8ba76d6..46318c2 100644 --- a/readme.md +++ b/readme.md @@ -11,7 +11,7 @@ To learn more about FSMB APIs, refer to the [Getting Started](https://github.com - Production: https://services-fcvs.fsmb.org - Authentication URL `/connect/token` - [Postman Collection](https://www.getpostman.com/collections/b59f8de00ca54eb654b7) -- [OpenAPI Specification](https://services-fcvs.fsmb.org/swagger/v1) +- [OpenAPI Specification](https://services-fcvs.fsmb.org/openapi/v1.json) [Run In Postman](https://app.getpostman.com/run-collection/1384052-bbfef0d8-d867-446d-8ae8-08d42b035ebe?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D1384052-bbfef0d8-d867-446d-8ae8-08d42b035ebe%26entityType%3Dcollection%26workspaceId%3D58240218-129c-4c2c-a71a-139a2efabdb2#?env%5BFCVS%20(Demo)%5D=W3siZW5hYmxlZCI6dHJ1ZSwia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9zZXJ2aWNlcy1mY3ZzLWRlbW8uZnNtYi5vcmcifSx7ImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJrZXkiOiJjbGllbnRJZCIsInZhbHVlIjoiRE9fTk9UX1NFVCJ9LHsiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsImtleSI6ImNsaWVudFNlY3JldCIsInZhbHVlIjoiRE9fTk9UX1NFVCJ9XQ==) From abed8c6012fd189685f90bc842f0eb43ce24bc9b Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Wed, 12 Aug 2026 14:29:18 -0500 Subject: [PATCH 10/12] Update OpenAPI links --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 46318c2..265f8e9 100644 --- a/readme.md +++ b/readme.md @@ -11,7 +11,7 @@ To learn more about FSMB APIs, refer to the [Getting Started](https://github.com - Production: https://services-fcvs.fsmb.org - Authentication URL `/connect/token` - [Postman Collection](https://www.getpostman.com/collections/b59f8de00ca54eb654b7) -- [OpenAPI Specification](https://services-fcvs.fsmb.org/openapi/v1.json) +- OpenAPI Specification: [JSON](https://services-fcvs-demo.fsmb.org/openapi/v1.json) [YAML](https://services-fcvs-demo.fsmb.org/openapi/v1.yaml) [Run In Postman](https://app.getpostman.com/run-collection/1384052-bbfef0d8-d867-446d-8ae8-08d42b035ebe?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D1384052-bbfef0d8-d867-446d-8ae8-08d42b035ebe%26entityType%3Dcollection%26workspaceId%3D58240218-129c-4c2c-a71a-139a2efabdb2#?env%5BFCVS%20(Demo)%5D=W3siZW5hYmxlZCI6dHJ1ZSwia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9zZXJ2aWNlcy1mY3ZzLWRlbW8uZnNtYi5vcmcifSx7ImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQiLCJrZXkiOiJjbGllbnRJZCIsInZhbHVlIjoiRE9fTk9UX1NFVCJ9LHsiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6InNlY3JldCIsImtleSI6ImNsaWVudFNlY3JldCIsInZhbHVlIjoiRE9fTk9UX1NFVCJ9XQ==) From b1bc99c12ff83108fc2cabfdfcf839ebb3fb3391 Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Tue, 18 Aug 2026 13:16:57 -0500 Subject: [PATCH 11/12] Updated text for FID length --- relnotes/relnotes-202608.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/relnotes/relnotes-202608.md b/relnotes/relnotes-202608.md index 39d43f7..22e2f15 100644 --- a/relnotes/relnotes-202608.md +++ b/relnotes/relnotes-202608.md @@ -48,5 +48,5 @@ The legacy fields will be removed in a future update. Some endpoints have been adjusted to better reflect the data or error being returned. -- Any endpoint accepting a FID now requires an exact 9-digit value. Previously less than 9 digits were allowed but would never be allowed. This resulted in no data being returned, e.g. 404 or 204. Now a 400 status is returned to reflect the invalid data. +- Any endpoint accepting a FID now requires an exact 9-digit value. Previously less than 9 digits were allowed but would return no results, e.g. 404 or 204. Now a 400 status is returned to reflect the invalid data. - Previously passing an invalid board code to endpoint resulted in a 404. This was confusing since some endpoints return 404s when the request is valid but no data is available. Now passing a board code that is invalid will result in an 403 Forbidden error with a message indicating the code is invalid. From d9afbebb6920d989765a0a24bb678b2c3cc2bbce Mon Sep 17 00:00:00 2001 From: mtaylorfsmb <38144840+mtaylorfsmb@users.noreply.github.com> Date: Wed, 19 Aug 2026 09:33:16 -0500 Subject: [PATCH 12/12] Update wording on bad board codes --- relnotes/relnotes-202608.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/relnotes/relnotes-202608.md b/relnotes/relnotes-202608.md index 22e2f15..e660047 100644 --- a/relnotes/relnotes-202608.md +++ b/relnotes/relnotes-202608.md @@ -49,4 +49,4 @@ The legacy fields will be removed in a future update. Some endpoints have been adjusted to better reflect the data or error being returned. - Any endpoint accepting a FID now requires an exact 9-digit value. Previously less than 9 digits were allowed but would return no results, e.g. 404 or 204. Now a 400 status is returned to reflect the invalid data. -- Previously passing an invalid board code to endpoint resulted in a 404. This was confusing since some endpoints return 404s when the request is valid but no data is available. Now passing a board code that is invalid will result in an 403 Forbidden error with a message indicating the code is invalid. +- Previously passing an invalid board code to any endpoint resulted in a 404. This was confusing since some endpoints return a 404 when the request is valid but no data is available. With this release passing an invalid board code will result in an 403 Forbidden error with a message indicating the code is invalid.