Summary

The current implementation of POST /v3/service_plans/:guid/visibility is somewhat inconsistent with REST semantics and allows operations beyond simply appending organizations. Specifically, it can also change the visibility type (e.g., to public or admin), which overlaps with the semantics of PATCH /v3/service_plans/:guid/visibility.

Problem

From a REST perspective:

• POST should be used to add new resources or associations (in this case, adding orgs to an existing visibility list).
• PATCH should be used to modify existing state (e.g., changing the visibility type to public or admin).

Currently, POST behaves more like a PATCH, as it allows changing the visibility type, not just appending orgs. This blurs the intended semantics and increases the risk of accidental type changes when clients are only trying to add organizations.

Proposed Change

I propose tightening the semantics of POST /v3/service_plans/:guid/visibility:

• Allow POST only when type = organization.
• Ensure the target plan already has visibility type organization. If the plan’s visibility type is not organization, the request should fail with an appropriate error (e.g., 422 Unprocessable Entity).

This ensures that:

• POST is used solely for appending organizations to organization-scoped plans.
• PATCH remains the correct method for changing the visibility type.

Compatibility / Migration

This change could break existing clients that currently use POST to modify visibility type. However, those clients can simply switch to using PATCH, which already supports the same behavior. This aligns both endpoints with clearer REST semantics going forward.