932483 - Proposed API - RandomUser

Status: NEW

(Participation Infrastructure :: API Requests, task)

Description

[Austin King [:ozten]]

To compliment the Users API, and to build "Mozilla Community Spotlight" we need an API that returns a random Mozillian from the mozillians.org database.

RandomUser

The RandomUser method of the Mozillians API returns one user's profile information, chosen at random from all vouched Mozillians.

Requires Authentication
    Yes
Authorized Applications
    Community sites, Mozilla Corporation sites

Endpoint

    https://mozillians.org/api/v1/random_user/

Parameters

    app_key
        Required string - The application’s API key
    app_name
        Required string - The application’s name
    country
        Optional string - Return users with matching country
    region
        Optional string - Return users with matching region
    city
        Optional string - Return users with matching city
    skills
        Optional string (comma-separated list) - Return users with matching skills
    languages
        Optional string (comma-separated list) - Return users with matching languages
    groups
        Optional string (comma-separated list) - Return users with matching groups
    limit
        Optional integer - Return some number of results Max: 500, Default: 20
    offset
        Optional integer - Skip some number of results Default: 0
    format
        Optional string (json/jsonp) - Format of the response Default: json

Return Codes

    Code 	Description
    200: 	OK Success!
    401: 	Wrong app_name or app_key OR application not activated OR application not authorized

Examples

Look up a user by email address:

    Request:

    /api/v1/random_user/?app_name=foobar&app_key=12345

    Response (Community and Mozilla Corporation site):

    {
        "meta":
        {
            "total_count": 1
        },
        "objects":
        [
            {
                "allows_community_sites": true,
                "allows_mozilla_sites": true,
                "bio": "I've been a web typographer for 12 years.",
                "city": "Topeka",
                "country": "United States",
                "date_mozillian": "2008-12-01",
                "date_vouched": 2011-06-25T13:16:40,
                "email": "[e-mail]",
                "full_name": "John Doe",
                "groups": "[(u'widgets',), (u'chocolate',)]",
                "id": "42",
                "ircname": "",
                "is_vouched": true,
                "languages": "[(u'hindi',), (u'english',)]",
                "photo": "https://mozillians.org/media/uploads/userprofile/3c5fcc399-bf2f-6caf-96fb-b40d9a03037269.jpg",
                "region": "Kansas",
                "resource_uri": "/api/v1/users/42/",
                "skills": "[(u'card tricks',), (u'css3',), (u'skydiving instructor',)]",
                "timezone": "America/Topeka",
                "url": "https://mozillians.allizom.org/u/john_doe/",
                "username": "john_doe",
                "vouched_by": 808,
                "website": "http://johndozer.geocities.com"
            }
        ]
    }

Adding filters for consistency, but they aren't a deal breaker.

Comment 1

[William Reynolds [:williamr]]

Thanks for proposing an API method! I think this a great way to support the Mozilla Community Spotlight site, and I can see this API endpoint having other valuable uses too.

ozten, would you be willing to submit a pull request for this new API method? It's unlikely that the commtools team will work on this before the end of the year given some other priorities. I don't want us to slow down your progress with the Mozilla Community Spotlight site though. If you're open to submitting a pull request, join us in #commtools on IRC and we'll help you with it.

(In reply to Austin King [:ozten] from comment #0)
> The RandomUser method of the Mozillians API returns one user's profile
> information, chosen at random from all vouched Mozillians.

>     limit
>         Optional integer - Return some number of results Max: 500, Default:
> 20

Just to clarify, does this API method return one user or multiple users? The description and the limit above seem to imply different things.

As an alternative approach to this proposed API, we could add an optional parameter called 'random' to the /users endpoint that would return random results. An API call with the 'random' parameter set and 'limit=1' set would return one random user. I'm not sure what the technical implications are, and it might be best to create the new API method that ozten suggested instead of modifying the existing /users endpoint. Just wanted to offer that for consideration.