Mozillians/API-Specification/List Users/

From MozillaWiki
Jump to: navigation, search

users

Returns user information based on search parameters.

Authentication

This method required authentication.

Arguments

Argument Type Required Mozilla App Only Description
app_key string Y N Your app key
app_name string Y N Your app name
is_vouched string
[true false]
N Y Flag to return users that are vouched or not.
username string N Y Return user with matching username.
ircname string N Y Return user with matching ircname.
email string N / Y (Required For Community) Y Return user with matching email.
country string N Y Return users with matching country.
region string N Y Return users with matching region.
city string N Y Return users with matching city.
skills string N Y Return users with matching skills. Skills can be comma separated to filter users with any matched skills.
languages string N Y Return users with matching languages. Languages can be comma separated to filter users with any matched languages.
groups string N Y Return users with matching groups. Groups can be comma separated to filter users with any matched groups.
limit integer N Y Limit answer to [number] results.
offset integer N Y Skip [number] results. Defaults to 0.
format string
[json jsonp]
N N Specifies format of result. Defaults to 'json'.

Arguments country, region, city, is_vouched, email, skills, languages, groups can be combined. The returned results will be logically ANDed.

Return Codes

Code Description
200: OK All OK ;)
401: Unauthorized Wrong app_name or app_key or App not activated

Examples: Community Apps

  • /api/v1/users/?app_name=foobar&app_key=12345&email=test@example.com
   {
      "meta":
      {
          "limit": 20,
          "next": null,
          "offset": 0,
          "previous": null,
          "total_count": 1
      },
      "objects":
      [
          {
              "email": "test@example.com",
              "is_vouched": true
          }
      ]
   }
  • /api/v1/users/?app_name=foobar&app_key=12345&email=test@example.com&format=xml
   <?xml version='1.0' encoding='utf-8'?>
   <response>
   <objects type="list">
   <object>
   <email>giorgos@mozilla.com</email>
   <is_vouched type="boolean">True</is_vouched>
   </object>
   </objects>
   <meta type="hash">
   <next type="null"/>
   <total_count type="integer">1</total_count>
   <previous type="null"/>
   <limit type="integer">20</limit>
   <offset type="integer">0</offset>
   </meta>
   </response>
  • /api/v1/users/?app_name=foobar&app_key=12345
 FORBIDDEN
  • /api/v1/users/1/?app_name=foobar&app_key=12345
 FORBIDDEN

Examples: Mozilla Apps

  • /api/v1/users/?app_name=foobar&app_key=12345
   {
      "meta":
      {
          "limit": 20,
          "next": null,
          "offset": 0,
          "previous": null,
          "total_count": 4
      },
      "objects":
      [
          {
              "username": "foobar",
              "ircname": "foobar",
              "bio": "",
              "city": "",
              "country": "",
              "full_name": "Foo Bar",
              "email": "test@example.com",
              "groups":
              [
                  "staff"
              ],
              "id": "1",
              "ircname": "",
              "is_vouched": true,
              "languages":
              [
              ],
              "last_updated": "2012-10-04T02:31:30",
              "photo": "",
              "region": "",
              "resource_uri": "/api/v1/user/1/",
              "skills":
              [
                  "python"
              ],
              "website": ""
          }
      ]
   }

Examples: Mozilla Apps: Query By User ID

  • /api/v1/users/1/?app_name=foobar&app_key=12345
   {
      "username": "foobar",
      "ircname": "foobar",
      "bio": "",
      "city": "",
      "country": "",
      "full_name": "Foo Bar",
      "email": "test@example.com",
      "groups":
      [
          "staff"
      ],
      "id": "1",
      "ircname": "",
      "is_vouched": true,
      "languages":
      [
      ],
      "last_updated": "2012-10-04T02:31:30",
      "photo": "",
      "region": "",
      "resource_uri": "/api/v1/user/1/",
      "skills":
      [
          "python"
      ],
      "website": ""
   }

Examples: Mozilla Apps: More Filters

Mozilla Apps can use more filters on results:

  • Filter by country:
 /api/v1/users/?app_name=foobar&app_key=12345&country=Greece
  • Filter by region:
 /api/v1/users/?app_name=foobar&app_key=12345&region=California
  • Filter by city:
 /api/v1/users/?app_name=foobar&app_key=12345&city=Mountain%20View
  • Filter by ircname:
 /api/v1/users/?app_name=foobar&app_key=12345&ircname=foobar
  • Filter by username:
 /api/v1/users/?app_name=foobar&app_key=12345&username=foobar
  • Filter by languages:
 /api/v1/users/?app_name=foobar&app_key=12345&languages=Greek
  • Filter by skills:
 /api/v1/users/?app_name=foobar&app_key=12345&skills=Python
  • Filter by groups:
 /api/v1/users/?app_name=foobar&app_key=12345&groups=Staff
  • Filter by name:
 /api/v1/users/?app_name=foobar&app_key=12345&name=foo
  • Filters can be combined, e.g. python and brazil:
 /api/v1/users/?app_name=foobar&app_key=12345&country=brazil&skills=python