Review PHP Community SDK challenges with API breaking changes

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Close this issue

Problem to solve

The PHP community SDK for the GitLab API is maintained by @GrahamCampbell. During a discussion with @jeffersonmartin who consumes the SDK for GitLab internal tools, Jeff asked if there was anything that GitLab can do to help make it easier.

Graham mentioned that there are some subtle but important breaking changes in our APIv4 that are discovered through trial and error, and aren't explicitly stated in the Changelog or are included in a broader feature/fix that isn't easily identifiable since we do not have a dedicated Changelog for the API. See Example 1 below.

Jeff has also noticed that breaking changes occur when other updates are made. See Example 2 below.

This issue is to review how we can improve the communication of changes to our API and ensure that breaking changes are properly versioned or mitigated through proper wording and/or documentation.

Example 1 - Updating a Group Label

The Groups/Update a group label API changed to move the label ID from a query string parameter into a URI parameter. This changes the expected URI of this endpoint.

GitLabPHP/Client:PR578
GitLab API Docs Reference - Current Version
GitLab MR - Parameter added
GitLab Commit - Parameter added
GitLab Commit - Deprecation Notice
v12.4.0 Changelog message: Add proper label REST API for update, delete and promote

    public function updateLabel(int $group_id, array $params)
    {
        return $this->put('groups/'.self::encodePath($group_id).'/labels', $params);
    }

    public function updateLabel(int $group_id, int $label_id, array $params)
    {
        return $this->put('groups/'.self::encodePath($group_id).'/labels/'.self::encodePath($label_id), $params);
    }

Update 2 - GitLab Group Fuzzy Searching

demosys-portal MR 73 (GitLab Internal) - Excerpted below

In GitLab v13.6, additional fuzzy searching functionality was added to the GitLab Groups API that we use for looking up the Training Users top-level group that session sub-groups are created under.

The fuzzy searching now includes the full path Training Users / Session 123456 / My Test Group - iu123456. So when searching for Training Users it returns a lot of results with a wildcard behavior instead of the explicitly named Training Users group.

!45729 (merged)

Workaround: Make change to use a defined environment/config variable with the Group ID for the Training Users group instead of a name lookup.

Proposal

Add headers to CHANGELOG for API Additions and API Breaking Changes.
Add tip/alerts to API documentation resource page under the endpoint heading specifying what GitLab version the endpoint, URI parameters, or query string parameters changed.
Add Changelog to top of each each API documentation resource page to cover all changes to this resource's endpoints

Who can address the issue

@deuley @axil @mjang1 @aqualls