Merge pull request #5416 from hypothesis/api-docs-groupid

Add docs for `groupid` on `POST /api/groups`

docs/_extra/api-reference/hypothesis.yaml

@@ -364,6 +364,10 @@ paths:
           description: Could not create group from your request
           schema:
             $ref: '#/definitions/Error'
+        '409':
+          description: Conflict
+          schema:
+            $ref: '#/definitions/ConflictError'
       security:
         - authClientForwardedUser: []
         - developerAPIKey: []

docs/_extra/api-reference/schemas/new-group.yaml

@@ -10,5 +10,15 @@ Group:
       type: string
       description: group description
       maxLength: 250
+    groupid:
+      type: string
+      pattern: "group:[a-zA-Z0-9._\\-+!~*()']{1,1024}@.*$"
+      description: >
+        <p><mark>NEW/EXPERIMENTAL</mark></p>
+        <p>For AuthClient-authenticated requests only.</p>
+
+        <p>Optional unique identifier for this group, in the format `"group:<unique_identifier>@<authority>"`, e.g.: `"group:my-own-unique-id-123@myauthority.com"`. The `authority` value must match the requesting client's authorized authority. </p>
+
+        <p>This property is intended to allow third-party authorized clients to set their own unique identifier for a group. As such, the value of the `unique_identifier` string must be unique within the `authority`. A uniqueness violation will result in an `HTTP 409: Conflict` response.</p>
   required:
     - name