2015.03.04 User API

Attendees: Ferdi, Steve Magoun, Matt Drayer, Andy, Christina, Piotr, Nimisha, Ned, Leslie

On Hangout: Dave O, Jim A, Vishal.

Clarifying questions:

Is this already in master?
- Parts are, yes: Account, profile, at v0
- Other parts are not: Preferences
- Deliverables being built by Arbisoft on this API for delivery later this month.
Considering it's already in master, what is the goal of this meeting?
- review the design, make sure it's what we want. Figure out how we can get to what we want.
Privacy: who should be able to call these methods, and what information can they get?
Why separate accounts from profiles?
- Your profile is something you are building to share, based on info in the account (except for pic and bio, which aren't in the account).
- Didn't want to tie profile directly to the info in the database.
  - wanted it to be a "virtual" view of the data.
- All info about account is available through the account endpoints
- Everything is set through account, profile is readonly.
  - Shouldn't that be a reason to keep only one, and get rid of the other?
  - the Profile endpoint serves the new profile page
    - anyone can view your profile page, but they can't view your account.
    - the APIs mirror that.
      - Can't we do that with authorization on top of a single endpoint?
        I can patch my account, others cannot, but everyone can read.
  - Is there a point later where profile has information that account doesn't?
    - One idea that hasn't been fully explored: course-specific fields in the profile.
  - Some things might be on the profile that don't come from the account:
    - courses you've taken, badges.

Concerns:

Privacy:
- who should be able to call these methods, and what information can they get?
- Global "Staff" users: they have access to everything, including updating!
  - Too many people have is_staff.
    - is_staff should be enablable, not always enabled.
  - Why do staff need to change user account information?
  - Maybe we should leave out the is_staff ability?
    - be safe now since we don't have a use case for the API to provide is_staff to change anything.
    - perhaps a sudo=True flag in the API?
  - What are the negative consequences if we start conservatively?
    - We aren't building UIs that would make use of the is-staff access now.
    - MITx needs read access, but not write for their scripting.
- DECISION: disallow is_staff write access for now. We'll learn more about what people want from it.
- Spec has been updated so that is_staff gives access for GET operations (both account and preference) only. PATCH/PUT/DELETE operations can only be done by the user owning the resource being modified.
Split account from profile, or use one endpoint?
- Preferences: could they be folded into account API?
  - Christina: We don't want to name all of the possible preference keys
  - Ferdi: this would reduce the number of API endpoints.
  - Ferdi: the preferences endpoints don't feel resource-based.
  - Ferdi: don't have a /preferences endpoint, just get the user object and it will have preferences on it.
  - Nimisha: criteria:
  - if the bulk of the payload could be an issue, then /preferences could be separate to reduce size of payload
  - if you want to query preferences, a separate endpoint would be useful.
- Piotr: I have enough "I don't knows" that I prefer one endpoint rather than three
- How will microservices affect this decision?
- It's odd that /profile can't accept a PUT, and to change the information, you PUT on /account.
- Authorization will be trickier if you combine the endpoints.
- Fewer, larger endpoints vs more, smaller endpoints
  - Dave prefers smaller
  - Christina prefers smaller
  - Nimisha thinks preferences should be separate, but accounts and profile seem too similar, and should be combined.
  - Ferdi wants to combine preferences into accounts.
- Spec has been updated to combine the account and profile APIs into one-- there will be no profile API at this time. We have decided to keep the preferences API separate.
API could get confused once things happen:
- Per-course profiles
- Integration with XBlocks
  - Other platforms using XBlocks may not use the same fields we do.
- Namespace prefixes could help.
  - preference for "edx." over "edx-platform."
  - Can't we use absence of namespace to mean "edx"?
- This API is particular to edx-platform, so why prefix the fields with "edx-platform"?
  - It's confusing if things have different names in different places. (XBlock user service vs. this API)
- Is this a concern for every API we build?
  - No: user information is so broad, it needs prefixes.
- Does account vs profile interact with this concern?
  - account can be very edx-specific, while profile could be more generic?
- We have decided not to namespace the account field names. Our thought is that these really are the edX account fields, and it seems unlikely that we would store fields from other sources (like Facebook) within edX accounts. The more likely place where namespaces would be needed would be a profile API, which we have deferred development of at this time. Also, leaving out namespaces now does not completely prevent namespaces in the future, as the absence of a namespace could signify the default "edX" namespace.
How will we support other profiles in the future? (Facebook, Google, etc)
Vishal: by default, the user's profile is public? ANSWERED.
- the default is configurable by site operator, and the "profile fields" are also.
- for edx.org: default visibility is all users
Growing number of APIs operating on the same resource. ANSWERED.
- Everything in the user_api django app will be refactored into the new APIs, or delegating to.
- (Except a few that aren't in the new API, like email_opt_in preferences, controlled by individual URLs)
Does this API provide for modifying roles? ANSWERED.
- This API doesn't provide for course settings like TA roles.
- Authorization is a separate service.
- Role information is per-course.
- Is there anything in this API that is per-course?
  - Not yet, but a user/course combined id could support it.
Authentication/Authorization
- We have both oauth and session authentication.
- How would someone write a script against this API?
  - The script would use OAuth2.
- Profile search: a logged-in user will be able to search profiles.
Can we prevent people from scraping all the public profiles? ANSWERED.
- Not really, other than rate-limiting, terms of service, etc.