Vridlo/api/vridlo.groups: Difference between revisions

From ALT Linux Wiki
(Created page with "== vridlo.group.slug == This allows accessing to the specified group record by <slug> URI-parameter. Added into API v1.0. === Path === /v1/groups/<slug> === Methods === =...")
 
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
== vridlo.group.index ==
It allows accessing to a list of groups, which are presented in the system. Do not poll this method more than once an hour.
Added into API v1.0.
=== Path ===
/v1/groups
=== Methods ===
==== GET ====
Returns a list of groups, which are presented in the system. Do not poll this method more than once an hour.
Added into API v1.0.
===== Authentication =====
This method requires NO authentication.
===== Arguments =====
* per_page (Optional)
Number of items to return per page. If this argument is omitted, it defaults to 10. The maximum allowed value is 50.
* page (Optional)
The page of results to return. If this argument is omitted, it defaults to 1.
NOTE: Arguments can be provided as arguments along with headers fields.
===== Example Response =====
[
  {
  "id": 1,
  "member_count": 2,
  "description": "Info group",
  "names": [
      {
        "kind": "name"
        "text": "group"
      },
      {
        "kind": "nickname"
        "text": "Bublo"
      }
  ],
  "member_slugs": [
      "user",
      "user1",
  ],
  "recitals": [
    {
        "kind": "email",
        "address": "group@gmail.com",
        "foremost": false
    },
    {
        "kind": "email",
        "address": "group@packages.altlinux.org",
        "foremost": true
    },
    {
        "kind": "slug",
        "address": "group",
        "foremost": false
    },
    {
        "kind": "jabber",
        "address": "group@jabber.ru",
        "foremost": false
    },
    {
        "kind": "website",
        "address": "http://group.me",
        "foremost": false
    },
    {
        "kind": "location",
        "address": {
          "x": "37.618448",
          "y": "55.753165",
          "grid": "yandex",
          "name": "Moskva. Kremlin. Granovita palata"
        },
        "foremost": false
    }
  ]
  }
]
===== Return Codes =====
* '''200''' (''OK'')
The resource list is accessible. Returned data responds to the current state of the resource list, and reading the list is finished.
* '''206''' (''Partial Content'')
The resource list is accessible. Returned data responds to the current state of the resource list, and reading the list is NOT finished yet.
* '''416''' (''Range Not Satisfiable'')
The resource list is accessible. But data can't be returned since range provided don't match the list boundaries.
* '''422.3''' (''SSL is required'')
SSL is required to access the Vridlo API.
* '''500''' (''Service currently unavailable'')
The requested service is temporarily unavailable.
== vridlo.group.slug ==
== vridlo.group.slug ==


Line 20: Line 127:
* '''names''' is ''array of [[Vridlo/type/Name|Name]]'' (Mandatory)
* '''names''' is ''array of [[Vridlo/type/Name|Name]]'' (Mandatory)
  Name array for the group.
  Name array for the group.
* '''admin''' is ''boolean'' (Optional)
Is the group admin, the field requires '''supergroup''' permission token to group model.
* '''description''' is ''string'' (Optional)
* '''description''' is ''string'' (Optional)
  Description of the group.
  Description of the group.
* '''recitals''' is ''array of [[Vridlo/type/Recital|Recital]]'' (Mandatory)
* '''recitals''' is ''array of [[Vridlo/type/Recital|Recital]]'' (Mandatory)
  Recital record array for the group.
  Recital record array for the group.
* '''member_slugs''' is ''array of string'' (Mandatory)
String record array for the group, that describes list of member slugs.


====== Sample request ======
====== Sample request ======
  {
  {
  "admin": false,
   "description": "Info group",
   "description": "Info group",
   "names": [
   "names": [
     {
     {
         "kind": "firstname"
         "kind": "name"
         "text": "group"
         "text": "group"
    },
    {
        "kind": "paternal"
        "text": "Batkovič"
    },
    {
        "kind": "lastname"
        "text": "Batkovič"
     },
     },
     {
     {
Line 48: Line 146:
         "text": "Bublo"
         "text": "Bublo"
     }
     }
  ],
  "member_slugs": [
      "user",
      "user1",
   ],
   ],
   "recitals": [
   "recitals": [
Line 84: Line 186:
  {
  {
   "id": 1,
   "id": 1,
   "sign_in_count": 2,
   "member_count": 2,
  "current_sign_in_at": "",
  "last_sign_in_at": "",
  "confirmed": false,
  "admin": false,
   "description": "Info group",
   "description": "Info group",
   "names": [
   "names": [
       {
       {
         "kind": "firstname"
         "kind": "name"
         "text": "group"
         "text": "group"
      },
      {
        "kind": "paternal"
        "text": "Batkovič"
      },
      {
        "kind": "lastname"
        "text": "Batkovič"
       },
       },
       {
       {
Line 107: Line 197:
         "text": "Bublo"
         "text": "Bublo"
       }
       }
  ],
  "member_slugs": [
      "user",
      "user1",
   ],
   ],
   "recitals": [
   "recitals": [
Line 188: Line 282:
  {
  {
   "id": "1",
   "id": "1",
   "sign_in_count": "2",
   "member_count": 2,
  "current_sign_in_at": "10.11.1970 10:10:10",
  "last_sign_in_at": "10.10.1970 10:10:10",
  "confirmed": true,
  "admin": false,
   "description": "Info group",
   "description": "Info group",
   "names": [
   "names": [
       {
       {
         "kind": "firstname"
         "kind": "name"
         "text": "group"
         "text": "group"
      },
      {
        "kind": "paternal"
        "text": "Batkovič"
      },
      {
        "kind": "lastname"
        "text": "Batkovič"
       },
       },
       {
       {
Line 211: Line 293:
         "text": "Bublo"
         "text": "Bublo"
       }
       }
  ],
  "member_slugs": [
      "user",
      "user1",
   ],
   ],
   "recitals": [
   "recitals": [
Line 284: Line 370:
* '''names''' is ''array of [[Vridlo/type/Name|Name]]'' (Optional)
* '''names''' is ''array of [[Vridlo/type/Name|Name]]'' (Optional)
  Name array for the group.
  Name array for the group.
* '''admin''' is ''boolean'' (Optional)
Is the group admin, the field requires '''supergroup''' permission token to group model.
* '''description''' is ''string'' (Optional)
* '''description''' is ''string'' (Optional)
  Description of the group.
  Description of the group.
* '''recitals''' is ''array of [[Vridlo/type/Recital|Recital]]'' (Optional)
* '''recitals''' is ''array of [[Vridlo/type/Recital|Recital]]'' (Optional)
  Recital record array for the group.
  Recital record array for the group.
* '''member_slugs''' is ''array of string'' (Optional)
String record array for the group, that describes list of member slugs.


====== Sample request ======
====== Sample request ======
  {
  {
  "admin": false,
   "description": "Info group",
   "description": "Info group",
   "names": [
   "names": [
     {
     {
         "kind": "firstname"
         "kind": "name"
         "text": "group"
         "text": "group"
    },
    {
        "kind": "paternal"
        "text": "Batkovič"
    },
    {
        "kind": "lastname"
        "text": "Batkovič"
     },
     },
     {
     {
Line 312: Line 389:
         "text": "Bublo"
         "text": "Bublo"
     }
     }
  ],
  "member_slugs": [
      "user",
      "user1",
   ],
   ],
   "recitals": [
   "recitals": [
Line 352: Line 433:
  {
  {
   "id": "1",
   "id": "1",
   "sign_in_count": "2",
   "member_count": 2,
  "current_sign_in_at": "10.11.1970 10:10:10",
  "last_sign_in_at": "10.10.1970 10:10:10",
  "confirmed": true,
  "admin": false,
   "description": "Info group",
   "description": "Info group",
   "names": [
   "names": [
       {
       {
         "kind": "firstname"
         "kind": "name"
         "text": "group"
         "text": "group"
      },
      {
        "kind": "paternal"
        "text": "Batkovič"
      },
      {
        "kind": "lastname"
        "text": "Batkovič"
       },
       },
       {
       {
Line 375: Line 444:
         "text": "Bublo"
         "text": "Bublo"
       }
       }
  ],
  "member_slugs": [
      "user",
      "user1",
   ],
   ],
   "recitals": [
   "recitals": [
Line 459: Line 532:
  {
  {
   "id": "1",
   "id": "1",
   "sign_in_count": "2",
   "member_count": 2,
  "current_sign_in_at": "10.11.1970 10:10:10",
  "last_sign_in_at": "10.10.1970 10:10:10",
  "confirmed": true,
  "admin": false,
   "description": "Info group",
   "description": "Info group",
   "names": [
   "names": [
       {
       {
         "kind": "firstname"
         "kind": "name"
         "text": "group"
         "text": "group"
      },
      {
        "kind": "paternal"
        "text": "Batkovič"
      },
      {
        "kind": "lastname"
        "text": "Batkovič"
       },
       },
       {
       {
Line 482: Line 543:
         "text": "Bublo"
         "text": "Bublo"
       }
       }
  ],
  "member_slugs": [
      "user",
      "user1",
   ],
   ],
   "recitals": [
   "recitals": [

Latest revision as of 12:03, 3 December 2019

vridlo.group.index

It allows accessing to a list of groups, which are presented in the system. Do not poll this method more than once an hour. Added into API v1.0.

Path

/v1/groups

Methods

GET

Returns a list of groups, which are presented in the system. Do not poll this method more than once an hour. Added into API v1.0.

Authentication

This method requires NO authentication.

Arguments
  • per_page (Optional)
Number of items to return per page. If this argument is omitted, it defaults to 10. The maximum allowed value is 50.
  • page (Optional)
The page of results to return. If this argument is omitted, it defaults to 1.

NOTE: Arguments can be provided as arguments along with headers fields.

Example Response
[
 {
  "id": 1,
  "member_count": 2,
  "description": "Info group",
  "names": [
     {
        "kind": "name"
        "text": "group"
     },
     {
        "kind": "nickname"
        "text": "Bublo"
     }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
    {
       "kind": "email",
       "address": "group@gmail.com",
       "foremost": false
    },
    {
       "kind": "email",
       "address": "group@packages.altlinux.org",
       "foremost": true
    },
    {
       "kind": "slug",
       "address": "group",
       "foremost": false
    },
    {
       "kind": "jabber",
       "address": "group@jabber.ru",
       "foremost": false
    },
    {
       "kind": "website",
       "address": "http://group.me",
       "foremost": false
    },
    {
       "kind": "location",
       "address": {
          "x": "37.618448",
          "y": "55.753165",
          "grid": "yandex",
          "name": "Moskva. Kremlin. Granovita palata"
       },
       "foremost": false
    }
  ]
 }
]
Return Codes
  • 200 (OK)
The resource list is accessible. Returned data responds to the current state of the resource list, and reading the list is finished.
  • 206 (Partial Content)
The resource list is accessible. Returned data responds to the current state of the resource list, and reading the list is NOT finished yet.
  • 416 (Range Not Satisfiable)
The resource list is accessible. But data can't be returned since range provided don't match the list boundaries.
  • 422.3 (SSL is required)
SSL is required to access the Vridlo API.
  • 500 (Service currently unavailable)
The requested service is temporarily unavailable.

vridlo.group.slug

This allows accessing to the specified group record by <slug> URI-parameter. Added into API v1.0.

Path

/v1/groups/<slug>

Methods

POST

Creates the group specified by <slug> URI-parameter using the set of properties passed as form data or get parameter array, and returns state of the created record as JSON.

Authentication

This method requires write authentication with write permission token to group model.

Arguments
  • names is array of Name (Mandatory)
Name array for the group.
  • description is string (Optional)
Description of the group.
  • recitals is array of Recital (Mandatory)
Recital record array for the group.
  • member_slugs is array of string (Mandatory)
String record array for the group, that describes list of member slugs.
Sample request
{
  "description": "Info group",
  "names": [
    {
       "kind": "name"
       "text": "group"
    },
    {
       "kind": "nickname"
       "text": "Bublo"
    }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
   {
      "kind": "email",
      "address": "group@gmail.com",
      "foremost": false
   },
   {
      "kind": "email",
      "address": "group@altlinux.org",
      "foremost": true
   },
   {
      "kind": "slug",
      "address": "group",
      "foremost": false
   },
   {
      "kind": "location",
      "address": {
         "x": "37.618448",
         "y": "55.753165",
         "grid": "yandex",
         "name": "Moskva. Kremlin. Senatskij palace"
      },
      "foremost": false
    }
  ]
}
Example Response

Good response with created record: 

{
  "id": 1,
  "member_count": 2,
  "description": "Info group",
  "names": [
     {
        "kind": "name"
        "text": "group"
     },
     {
        "kind": "nickname"
        "text": "Bublo"
     }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
    {
       "kind": "email",
       "address": "group@gmail.com",
       "foremost": false
    },
    {
       "kind": "email",
       "address": "group@altlinux.org",
       "foremost": true
    },
    {
       "kind": "slug",
       "address": "group",
       "foremost": false
    },
    {
       "kind": "jabber",
       "address": "group@jabber.ru",
       "foremost": false
    },
    {
       "kind": "website",
       "address": "http://group.me",
       "foremost": false
    },
    {
       "kind": "location",
       "address": {
          "x": "37.618448",
          "y": "55.753165",
          "grid": "yandex",
          "name": "Moskva. Kremlin. Senatskij palace"
       },
       "foremost": false
    }
  ]
}

Error response 423: 

{
  "error_code": 3
}
Return Codes
  • 200 (OK)
The resource wasn't found, and was created. Returned data responds to the current state of the resource.
  • 422.3 (SSL is required)
SSL is required to access the Vridlo API.
  • 422.5 (Invalid incoming data)
The incoming data is invalid. See details for help.
  • 404 (Not Found)
The record with provided slug is not found.
  • 500 (Internal Server Error)
The Internal Server Error has occurred.

GET

Gets properties of the group specified by <slug> URI-parameter, and returns then as JSON. Do not poll this method more than once an hour.

Authentication

This method requires NO authentication.

Arguments

This method requires NO arguments.

Example Response

Good response: 

{
  "id": "1",
  "member_count": 2,
  "description": "Info group",
  "names": [
     {
        "kind": "name"
        "text": "group"
     },
     {
        "kind": "nickname"
        "text": "Bublo"
     }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
    {
       "kind": "email",
       "address": "group@gmail.com",
       "foremost": false
    },
    {
       "kind": "email",
       "address": "group@altlinux.org",
       "foremost": true
    },
    {
       "kind": "slug",
       "address": "group",
       "foremost": false
    },
    {
       "kind": "jabber",
       "address": "group@jabber.ru",
       "foremost": false
    },
    {
       "kind": "website",
       "address": "http://group.me",
       "foremost": false
    },
    {
       "kind": "location",
       "address": {
          "x": "37.618448",
          "y": "55.753165",
          "grid": "yandex",
          "name": "Moskva. Kremlin. Senatskij palace"
       },
       "foremost": false
    }
  ]
}

Error response 423: 

{
  "error_code": 3
}
Return Codes
  • 200 (OK)
The resource was found and is accessible. Returned data responds to the current state of the resource.
  • 422.3 (SSL is required)
SSL is required to access the Vridlo API.
  • 404 (Not Found)
The record with provided slug is not found.
  • 500 (Internal Server Error)
The Internal Server Error has occurred.

PUT/PATCH

Sets one or many properties of the group specified by <slug> URI-parameter, and returns updated state as JSON.

Authentication

This method requires write authentication with write permission token to group model.

Arguments

NOTE: Blank fields will be skipped, new array fields will be appended

  • names is array of Name (Optional)
Name array for the group.
  • description is string (Optional)
Description of the group.
  • recitals is array of Recital (Optional)
Recital record array for the group.
  • member_slugs is array of string (Optional)
String record array for the group, that describes list of member slugs.
Sample request
{
  "description": "Info group",
  "names": [
    {
       "kind": "name"
       "text": "group"
    },
    {
       "kind": "nickname"
       "text": "Bublo"
    }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
   {
      "kind": "email",
      "address": "group@gmail.com",
      "foremost": false
   },
   {
      "kind": "email",
      "address": "group@altlinux.org",
      "foremost": true
   },
   {
      "kind": "slug",
      "address": "group",
      "foremost": false
   },
   {
      "kind": "location",
      "address": {
         "x": "37.618448",
         "y": "55.753165",
         "grid": "yandex",
         "name": "Moskva. Kremlin. Senatskij palace"
      },
      "foremost": false
    }
  ]
}
Example Request

PUT:/v1/groups/ca?name=Core_Assembler

Example Response

Good response: 

{
  "id": "1",
  "member_count": 2,
  "description": "Info group",
  "names": [
     {
        "kind": "name"
        "text": "group"
     },
     {
        "kind": "nickname"
        "text": "Bublo"
     }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
    {
       "kind": "email",
       "address": "group@gmail.com",
       "foremost": false
    },
    {
       "kind": "email",
       "address": "group@altlinux.org",
       "foremost": true
    },
    {
       "kind": "slug",
       "address": "group",
       "foremost": false
    },
    {
       "kind": "jabber",
       "address": "group@jabber.ru",
       "foremost": false
    },
    {
       "kind": "website",
       "address": "http://group.me",
       "foremost": false
    },
    {
       "kind": "location",
       "address": {
          "x": "37.618448",
          "y": "55.753165",
          "grid": "yandex",
          "name": "Moskva. Kremlin. Senatskij palace"
       },
       "foremost": false
    }
  ]
}

Error response 423: 

{
  "error_code": 3
}
Return Codes
  • 200 (OK)
The resource was found and is accessible. Changes were made on the resource successfully. Returned data responds to the current state of the resource.
  • 204 (No Content)
The resource was found and is accessible. But no changes were made on the resource.
  • 422.3 (SSL is required)
SSL is required to access the Vridlo API.
  • 422.5 (Invalid incoming data)
The incoming data is invalid. See details for help.
  • 404 (Not Found)
The record with provided id/slug is not found.
  • 500 (Internal Server Error)
The Internal Server Error has occurred.

DELETE

Destroys the group specified by <slug> URI-parameter, and returns state of the destroyed record as JSON.

Authentication

This method requires write authentication with write permission token to group model.

Arguments

This method requires NO arguments.

Example Response

Good response returning deleted record: 

{
  "id": "1",
  "member_count": 2,
  "description": "Info group",
  "names": [
     {
        "kind": "name"
        "text": "group"
     },
     {
        "kind": "nickname"
        "text": "Bublo"
     }
  ],
  "member_slugs": [
     "user",
     "user1",
  ],
  "recitals": [
    {
       "kind": "email",
       "address": "group@gmail.com",
       "foremost": false
    },
    {
       "kind": "email",
       "address": "group@altlinux.org",
       "foremost": true
    },
    {
       "kind": "slug",
       "address": "group",
       "foremost": false
    },
    {
       "kind": "jabber",
       "address": "group@jabber.ru",
       "foremost": false
    },
    {
       "kind": "website",
       "address": "http://group.me",
       "foremost": false
    },
    {
       "kind": "location",
       "address": {
          "x": "37.618448",
          "y": "55.753165",
          "grid": "yandex",
          "name": "Moskva. Kremlin. Senatskij palace"
       },
       "foremost": false
    }
  ]
}

Error response 423: 

{
  "error_code": 3
}
Return Codes
  • 200 (OK)
The resource was found and is accessible, and successfully destroyed. Returned data responds to the state of the destroyed resource.
  • 422.3 (SSL is required)
SSL is required to access the Vridlo API.
  • 404 (Not Found)
The record with provided slug is not found.
  • 500 (Internal Server Error)
The Internal Server Error has occurred.