Overview

This page shows the usage of the Group API, please see the following for more details.

Documents & examples

LIST

Method: GET

URL: /rest_api/v1/auth/groups/

Query Params:

  • name (string)
  • permission_app_label (string)
  • permission_codename (string)
  • permission_model (string)
  • ordering (string) Comma separated list of fields for ordering results.
    • To sort by a field in descending order, prefix its name with minus (e.g. -name).
    • Use double underscores for nested field names (e.g. parent__child for {"parent": {"child": ...}}).

Following filters can be used to show only specific fields. This can make response time faster. Format is list or single value (JSON: {"fields": ["a","b"]} or {"fields": "a"}, in URL: ?fields=a&fields=b).

  • fields (list | string) Fields to display (other fields will be hidden).
  • exclude_fields: (list | string) Fields NOT to display (overrules fields).

Response: a paged list of following objects

{
    "name": "string", 
    "permissions": [
        "permission"
    ], 
    "url (read-only)": "url"
}

Example:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/",
            "name": "group_add_group",
            "permissions": [
                {
                    "codename": "add_group",
                    "app_label": "auth",
                    "model": "group"
                }
            ]
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/2/",
            "name": "group_change_change",
            "permissions": [
                {
                    "codename": "change_change",
                    "app_label": "changeset",
                    "model": "change"
                }
            ]
        }
    ]
}

RETRIEVE

Method: GET

URL: /rest_api/v1/auth/groups/{instance_pk}/

Response:

{
    "name": "string", 
    "permissions": [
        "permission"
    ], 
    "url (read-only)": "url"
}

Example:

# curl command
curl -H "Content-Type: application/json" https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/
# output
{
  "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/,
  "name": "group_add_group",
  "permissions": [
      {
          "codename": "add_group",
          "app_label": "auth",
          "model": "group"
      }
  ]
}

UPDATE

Method:

PUT: to update name and permissions

PATCH: to update name or permissions

URL: /rest_api/v1/auth/groups/{instance_pk}/

Response:

{
    "name": "string", 
    "permissions": [
        "permission"
    ], 
    "url (read-only)": "url"
}

Example:

PUT:

# cat put_data.json
{
    "name": "new_group",
    "permissions": [
        {
            "codename": "change_change",
            "app_label": "changeset",
            "model": "change"
        },
        {
            "codename": "add_group",
            "app_label": "auth",
            "model": "group"
        }
    ]
}
# curl command
curl -H "Content-Type: application/json" \
     -X PUT \
     --data @put_data.json  \
    https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/
# output
{
  "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/",
  "name": "new_group",
  "permissions": [
      {
          "codename": "change_change",
          "app_label": "changeset",
          "model": "change"
      },
      {
          "codename": "add_group",
          "app_label": "auth",
          "model": "group"
      }
  ]
}

PATCH:

# cat patch_data.json
{
    "permissions": [
        {
            "codename": "change_change",
            "app_label": "changeset",
            "model": "change"
        },
        {
            "codename": "add_group",
            "app_label": "auth",
            "model": "group"
        }
    ]
}
# curl command
curl -H "Content-Type: application/json" \
     -X PATCH \
     --data @patch_data.json  \
    https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/
# output
{
  "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/",
  "name": "group_add_group",
  "permissions": [
      {
          "codename": "change_change",
          "app_label": "changeset",
          "model": "change"
      },
      {
          "codename": "add_group",
          "app_label": "auth",
          "model": "group"
      }
  ]
}

It is possible to update multiple objects in one request. Use the PUT or PATCH method with the same url as for listing/creating objects. The request body should contain an object, where keys are identifiers of objects to be modified and their values use the same format as normal update.

Browsable GET

GET /rest_api/v1/auth/groups/
HTTP 200 OK
Allow: GET, PUT, PATCH, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "count": 330,
    "next": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/?page=2",
    "previous": null,
    "results": [
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/1/",
            "name": "gitfedorahosted",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/2/",
            "name": "sysadmin-web",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/3/",
            "name": "sysadmin-cvs",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/4/",
            "name": "sysadmin-noc",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/5/",
            "name": "sysadmin-tools",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/6/",
            "name": "gitmoksha",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/7/",
            "name": "gitfas",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/8/",
            "name": "bzrpackagedb",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/9/",
            "name": "gitfuss",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/10/",
            "name": "gitsupybot-fedora",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/11/",
            "name": "bzrkitchen",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/12/",
            "name": "infra-sig",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/13/",
            "name": "sysadmin",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/14/",
            "name": "gitbadges",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/15/",
            "name": "sysadmin-logs",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/16/",
            "name": "sysadmin-badges",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/17/",
            "name": "sysadmin-datanommer",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/18/",
            "name": "fedmsg-announce",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/19/",
            "name": "packager",
            "permissions": []
        },
        {
            "url": "https://pdc.fedoraproject.org/rest_api/v1/auth/groups/20/",
            "name": "sysadmin-main",
            "permissions": []
        }
    ]
}