Skip to content

API Documentation

Jump to bottom
Will Wang edited this page Jun 15, 2020 · 46 revisions

Note: All of the endpoints documented below are prefixed with /api/v1/, which can be changed in the file backend/pryde_backend/urls.py

Sections

User Related Endpoints

GET /users/

Description: Returns a list of all users who have verified their emails.

Permissions: None

Parameters/Payload: None

Example response:

[
  {
    "pk": 1,
    "type": "user",
    "profile_picture": "https://prydeconnect.bctr.cornell.edu/api/media/profile_pictures/pic.jpg",
    "first_name": "John",
    "last_name": "Smith",
    "role": "Practitioner",
    "affiliation": "Cornell University",
    "locatedAtCornell": true,
    "locatedAtCCE": false,
    "researchInterests": ["foo", "bar"],
    "location": "Ithaca, NY",
    "email": "test@gmail.com",
    "numProjects": 0,
    "date_joined": "2020-01-13T20:18:18.596428Z"
  },
  ...
]

Notes:

  • type is either "user" or "project", used to determine what kind of card style to display on the website
  • role is either "Practitioner" or "Researcher"
  • locatedAtCornell and locatedAtCCE are set during the signup process and are used to display the Cornell and CCE badges on user profiles
  • researchInterests is simply an array of strings

GET /user/

Description: Returns the profile information of the currently logged in user.

Permissions: IsAuthenticated, user must provide an authentication token to access this endpoint

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }.

Example response:

Valid authentication token:

{
    "id": 1,
    "projects": [
        {
            "pk": 12,
            "type": "project",
            "name": "Project Name",
            "owner": {
                "pk": 2,
                "first_name": "John",
                "last_name": "Smith",
                "affiliation": "Cornell University",
                "location": "Cornell University",
                "email": "test@gmail.com",
                "phone": "+1234567890",
                "website": "",
                "type": "user",
                "role": "Researcher"
            },
            "status": "In Progress",
            "summary": "",
            "ageRanges": [
                "Young teens (12-14 years)"
            ],
            "researchTopics": [
                "Education & Learning"
            ],
            "deliveryModes": [
                "Afterschool programs"
            ],
            "datePosted": "2020-04-23T16:30:53.298319Z",
            "visible": true
        }
    ],
    "role": "Researcher",
    "researchInterests": [
        "Diversity Equity & Inclusion"
    ],
    "ageRanges": [
        "Teenagers (15-17 years)"
    ],
    "deliveryModes": [],
    "first_name": "Foo",
    "last_name": "Bar",
    "date_joined": "2020-01-23T02:44:42.145212Z",
    "locatedAtCornell": true,
    "locatedAtCCE": false,
    "displayRole": "Faculty",
    "affiliation": "BCTR",
    "location": "Cornell University",
    "email": "foo@gmail.com",
    "phone": "",
    "website": "http://example.com",
    "researchDescription": "",
    "roles": ["role1", "role2"],
    "researchNeeds": "",
    "evaluationNeeds": "",
    "profile_picture": "https://prydeconnect.bctr.cornell.edu/api/media/profile_pictures/pic.jpg"
}

Invalid authentication token:

{
    "detail": "Invalid token."
}

Notes:

  • id and pk are interchangeable, they refer to the number that uniquely identifies a project or user.
  • researchInterests/researchTopics/deliveryModes/ageRanges/roles are just arrays of strings, populated by options selected by the user during signup
  • owner in a project object refers to the user that created the project
  • visible in a project object is true if the user chose to keep the project visible on their profile, false if otherwise

GET /user/:id/

Description: Returns the user that is identified by the parameter id.

Permissions: None

Parameters/Payload: :id, refers to the unique number corresponding to each user

Example response:

User found:

Refer to GET /user/, same response schema

User not found:

{
    "detail": "Not found."
}

Notes:

  • This endpoint has the same response schema as GET /user/ except the project object does not have a visible field. Instead, any project the user set showProjectOnProfile = false for will not be returned in the response.

PUT /user/update/

Description: Updates user's profile information.

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being updated

Parameters/Payload:

Requires the headers { "Content-Type": "application/json", "Authorization": "Token <your_auth_token>" }

Payload schema:

{
    "role": 1,
    "first_name": "Samantha",
    "last_name": "Johnson",
    "locatedAtCornell": false,
    "locatedAtCCE": false,
    "displayRole": "Practice Focused Role",
    "affiliation": "Cornell University",
    "location": "Ithaca, NY",
    "email": "test@gmail.com",
    "phone": "+1234567890",
    "website": "http://example.com",
    "researchInterests": [
        "Education & Learning",
        "Peer Relationships"
    ],
    "researchDescription": "I love doing research",
    "roles": [
        "Design youth programs",
        "Train volunteers"
    ],
    "ageRanges": [
        "Young adults (18-24 years)"
    ],
    "deliveryModes": [
        "Clubs"
    ],
    "researchNeeds": "",
    "evaluationNeeds": ""
}

Example response: HTTP status 200 if successful, 400 if an error occurred.

Notes:

  • role is 1 for Practitioner, 2 for Researcher

DELETE /user/:id/delete/

Description: Deletes the user corresponding to id

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being deleted

Parameters/Payload: :id, refers to the unique number corresponding to each user. Requires the header { "Authorization": "Token <your_auth_token>" }

Example response: HTTP status 204 if successful, 400 if an error occurred.

POST /user/picture/

Description: Replaces the existing profile picture file or uploads a new one if did not previously exist.

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being updated

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>", "Content-Type": "multipart/form-data" }. Payload must have a key of file with the value being the uploaded file data.

Example response: HTTP status 201 if successful, 400 if file was over 3MB or an error occurred.

PUT /user/email/

Description: Changes the email attached to the user's profile/login information

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being updated

Parameters/Payload:

Requires the headers { "Authorization": "Token <your_auth_token>" }.

Payload schema: { "email": "test@gmail.com" }.

Example response: HTTP status 200 if successful, 400 if an error occurred.

GET /user/preferences/

Description: Returns the logged in user's email preferences.

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being updated

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }

Example response:

[
  {
    "type": "1",
    "preferenceName": "researchTopics",
    "preferenceValue": "Peer Relationships"
  },
  ...
]

Notes:

  • type is either 1 or 2, with 1 referring to a project email preference and 2 referring to a user email preference.
  • preferenceName is one of researchInterest/researchTopic/deliveryMode/ageRange

POST /user/preferences/update/

Description: Updates the email preferences of the logged in user. Deletes any previously existing email preferences and saves new ones.

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being updated

Parameters/Payload:

Requires the headers { "Authorization": "Token <your_auth_token>" }

Payload schema:

{
  "preferences": [
    {
      "type": 1,
      "name": "deliveryMode",
      "value": "Clubs"
    },
    {
      "type": 2,
      "name": "ageRange",
      "value": "Infants (0-1 year)"
    },
    ...
  ]
}

Example response: HTTP status 201 if successful, 400 if an error occurred.

Notes:

  • type is either 1 or 2, with 1 referring to a project email preference and 2 referring to a user email preference.
  • preferenceName is one of researchInterest/researchTopic/deliveryMode/ageRange

DELETE /user/preferences/delete/

Description: Unsubscribes logged in user from monthly newsletter by deleting all email preferences.

Permissions: CanEditDeleteUser and IsAuthenticated, user making request must be authenticated and be the user that is being updated

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }

Example response: HTTP status 204 if successful, 400 if an error occurred, 404 if user had no email preferences

Project Related Endpoints

GET /projects/

Description: Returns a list of all projects

Permissions: None

Parameters/Payload: None

Example response:

[
  {
    "pk": 1,
    "type": "project",
    "name": "Project Name",
    "owner": {
      "pk": 2,
      "first_name": "John",
      "last_name": "Smith",
      "affiliation": "BCTR",
      "location": "Cornell University",
      "email": "test@gmail.com",
      "phone": "+1234567890",
      "website": "",
      "type": "user",
      "role": "Researcher"
    },
    "status": "In Progress",
    "summary": "Project summary.",
    "ageRanges": [
      "Middle childhood (9-11 years)"
    ],
    "researchTopics": [
      "Science Technology Engineering & Math (STEM)"
    ],
    "deliveryModes": [
      "Online survey"
    ],
    "datePosted": "2020-01-14T21:31:49.111408Z",
    "visible": true
  },
  ...
]

Notes:

  • type is either "user" or "project", used to determine what kind of card style to display on the website
  • role is either "Practitioner" or "Researcher"
  • status is one of "Not Started", "In Progress", or "Completed"
  • The visible field is still returned in the response because the same serializer for projects is used on the profile page and browse page

GET /project/:id/

Description: Returns the project identified with the number id

Permissions: None

Parameters/Payload: None

Example response:

{
  "id": 1,
  "status": "In Progress",
  "owner": {
    "pk": 2,
    "first_name": "John",
    "last_name": "Smith",
    "affiliation": "BCTR",
    "location": "Cornell University",
    "email": "test@gmail.com",
    "phone": "+1234567890",
    "website": "",
    "type": "user",
    "role": "Researcher"
  },
  "collaborators": [
    {
      "pk": 3,
      "type": "user",
      "profile_picture": "/api/media/profile_pictures/pic.jpg",
      "first_name": "Foo",
      "last_name": "Bar",
      "role": "Researcher",
      "affiliation": "BCTR",
      "locatedAtCornell": true,
      "locatedAtCCE": false,
      "researchInterests": [
        "Positive Youth Development"
      ],
      "location": "Cornell University",
      "email": "test1@gmail.com",
      "numProjects": 2,
      "date_joined": "2020-01-13T20:18:18.596428Z"
    }
  ],
  "ageRanges": [
    "Young teens (12-14 years)"
  ],
  "researchTopics": [
    "Education & Learning"
  ],
  "deliveryModes": [
    "Online survey"
  ],
  "additionalFiles": [
    {
      "file_path": "https://prydeconnect.bctr.cornell.edu/api/media/project_files/file.pdf",
      "file_name": "File.pdf",
      "pk": 3
    }
  ],
  "name": "Project Name",
  "summary": "Project summary.",
  "timeline": "Ending in 2020",
  "commitmentLength": "Less than 30 minutes",
  "incentives": "Participants will recieve a $10 electronic gift card to Amazon.com",
  "additionalInformation": "",
  "datePosted": "2020-01-14T21:31:49.111408Z",
  "alternateContact": {
    "email": "",
    "phone": "",
    "website": "",
    "last_name": "",
    "first_name": ""
  },
  "alternateLocation": ""
}

Notes:

  • owner is the user that submitted and created the project
  • collaborators must be another user on the website, they represent people that are also working on the project
  • additionalFiles are any files the user uploaded to the project
  • alternateContact and alternateLocation are for the user to specify alternate contact information, by default a project page displays the user's information

POST /project/create/

Description: Creates a new project under the logged in user.

Permissions: IsAuthenticated, user must provide an authentication token

Parameters/Payload:

Requires the headers { "Content-Type": "application/json", "Authorization": "Token <your_auth_token>" }

Payload schema:

{
  "name": "Project Name",
  "status": 1,
  "summary": "Project summary",
  "researchTopics": ["research topic"],
  "ageRanges": ["age range],
  "deliveryModes": ["delivery mode"],
  "timeline": "timeline",
  "commitmentLength": "commitment length",
  "incentives": "none",
  "additionalInformation": "",
  "alternateContact": {
     "first_name": "",
      "last_name": "",
      "email": "",
      "phone": "",
      "website": ""
  },
  "alternateLocation": ""
}

Example response: HTTP status 201 if successful, 400 if an error occurred.

Notes:

  • status is 1 for Completed, 2 for In Progress, 3 for Not Started

PUT /project/:id/update/

Description: Updates the project information of the project identified by id

Permissions: IsAuthenticated and CanEditProject, user must provide an authentication token and must be either the project owner or a collaborator with edit permissions.

Parameters/Payload:

Requires the headers { "Content-Type": "application/json", "Authorization": "Token <your_auth_token>" }

Payload schema:

Same as POST /project/create/

Example response: HTTP status 200 if successful, 400 if an error occurred.

Notes:

  • status is 1 for Completed, 2 for In Progress, 3 for Not Started

DELETE /project/:id/delete/

Description: Deletes the project identified by id

Permissions: IsAuthenticated and `CanDeleteProject, user must provide an authentication token and be either the project owner or a collaborator with delete permissions.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }

Example response: HTTP status 204 if successful, 400 if an error occurred.

POST /project/:id/file/

Description: Uploads a file that is associated with the project identified by id.

Permissions: IsAuthenticated and `CanEditProject, user must provide an authentication token and be either the project owner or a collaborator with edit permissions.

Parameters/Payload: Requires the headers { "Content-Type": "multipart/form-data", "Authorization": "Token <your_auth_token>" }. Payload must have a key of file with the value being the uploaded file data.

Example response: HTTP status 201 if successful, 400 if an error occurred.

If :id is not a valid project id, then HTTP status code 404 will be returned with the response body { "message": "Project not found." }

DELETE /project/:project_id/file/:file_id/delete/

Description: Deletes the file identified by file_id that is associated with the project identified by project_id.

Permissions: IsAuthenticated and `CanEditProject, user must provide an authentication token and be either the project owner or a collaborator with edit permissions.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }.

Example response: HTTP status 204 if successful, 400 if an error occurred.

If :project_id is not a valid project id, then HTTP status code 404 will be returned with the response body { "message": "Project not found." }. Similarly, if :file_id is not a valid file id for the project specified then a response body { "message": "File not found." } will be returned with status code 404.

Collaborator Related Endpoints

GET /project/:id/collaborators/

Description: Retrieves the collaborators for the project identified by id

Permissions: None

Parameters/Payload: None

Example response:

[
  {
    "pk": 1,
    "editPermission": false,
    "deletePermission": false,
    "editCollaboratorsPermission": false,
    "email": "test@gmail.com",
    "first_name": "Foo",
    "last_name": "Bar"
  },
  ...
]

Notes:

  • Permissions of a collaborator define what they are allowed to do with a project they are a collaborator of

POST /project/:id/collaborator/add/

Description: Adds a collaborator to the project identified by id

Permissions: IsAuthenticated and CanEditCollaborators, user must provide an authentication token and either be the owner of the project or a collaborator with the permission to edit collaborators.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }.

Payload schema:

{
  "user": 1,
  "editPermission": true,
  "deletePermission": true,
  "editCollaboratorsPermission": true
}

Example response: HTTP status 201 if successful, 400 if an error occurred or user making request did not have the proper permissions.

Notes:

  • user is the id of the user that is being added as a collaborator. As a result, for a collaborator to be added to a project they must have an account on PRYDE Connect

PUT /project/:id/collaborator/update/

Description: Updates a collaborator already associated to the project identified by id

Permissions: IsAuthenticated and CanEditCollaborators, user must provide an authentication token and either be the owner of the project or a collaborator with the permission to edit collaborators.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>", "Content-Type": "application/json" }.

Payload schema:

Same as POST /project/:id/collaborator/add/

Example response: HTTP status 200 if successful, 404 if project not found or collaborator was not a pre-existing collaborator of the project, 400 if an error occurred or user making request did not have the proper permissions.

DELETE /project/:id/collaborator/delete/

Description: Deletes a collaborator associated to the project identified by id

Permissions: IsAuthenticated and CanEditCollaborators, user must provide an authentication token and either be the owner of the project or a collaborator with the permission to edit collaborators.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>", "Content-Type": "application/json" }.

Payload schema:

{
  "user": 1
}

Example response: HTTP status 204 if successful, 404 if project not found or collaborator was not a pre-existing collaborator of the project, 400 if an error occurred or user making request did not have the proper permissions.

Notes:

  • Same as POST /project/:id/collaborator/add/, the user field is the id of the user being removed from the list of collaborators on the project

PUT /project/:id/togglevisibility/

Description: Toggles whether or not the project identified by id is shown on the collaborator's profile and appears in the project's collaborators list.

Permissions: IsAuthenticated and IsCollaborator, user must provide an authentication token and already be a collaborator on the project.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>" }.

Example response: HTTP status 200 if successful, 404 if project not found, 400 if an error occurred.

Notes:

  • Same as POST /project/:id/collaborator/add/, the user field is the id of the user being removed from the list of collaborators on the project

GET /project/:id/permissions/

Description: Retrieves the permissions the user making the request has for the project identified by id

Permissions: IsAuthenticated, user must provide an authentication token.

Parameters/Payload: Requires the headers { "Authorization": "Token <your_auth_token>", "Content-Type": "application/json" }.

Example response:

{
  "editPermission": true,
  "deletePermission": true,
  "editCollaboratorsPermission": true,
  "isCollaborator": true,
  "showProjectOnProfile": true
}

Notes:

  • If any of the permission fields are true, then isCollaborator will be true as well. isCollaborator is true if the user making the request is a collaborator on the project and not the owner, otherwise it will be false.
  • showProjectOnProfile will be true or false if the user making the request is a collaborator on the project, otherwise it will be null

Search Related Endpoints

POST /filter/

Description: Returns a filtered list of projects or users. The algorithm is as follows:

  • Separate filter categories together are AND'd together and values within the same filter category are OR'd together. This is AND'd together with the results matching the query string.
    • Ex: If you filtered for a project with Not Started/In Progress selected for the Status filter category and Animal Science/Agriculture selected for the Research Topic filter category and the query string "test", projects in the set {"Not Started" ∪ "In Progress"} ∩ {"Animal Science" ∪ "Agriculture"} ∩ {"test"} would be returned.
  • For projects, the query string matches on the project owner's first/last name, project name, research topics, and summary
  • For users, the query string matches on the user's name, email, location, research needs, and research description

Permissions: None

Parameters/Payload:

Payload schema:

Searching for research partners (users)

{
  q: "your query here",
  category: "partners",
  ageranges: ["Toddlers (2-3 years)", "Young teens (12-14 years)"],
  deliverymodes: ["Summer Youth Employment Opportunities", "In-school Programming"],
  location: ["Broome", "Fulton"],
  researchinterest: ["Diversity Equity & Inclusion", "Environment & Sustainability", "Agriculture"],
  researchtopic: ["Career Readiness", "Education & Learning", "Energy"],
  status: ["Not Started", "In Progress"]
}

Searching for projects

{
  q: "your query here",
  category: "projects",
  ageranges: ["Toddlers (2-3 years)", "Young teens (12-14 years)"],
  deliverymodes: ["Summer Youth Employment Opportunities", "In-school Programming"],
  location: ["Broome", "Fulton"],
  researchinterest: ["Diversity Equity & Inclusion", "Environment & Sustainability", "Agriculture"],
  researchtopic: ["Career Readiness", "Education & Learning", "Energy"],
  status: ["Not Started", "In Progress"]
}

Example response: Has same response schema as GET /users/ or GET /projects/, just with only the relevant users or projects returned.

Notes:

  • HTTP verb convention is violated here for reasons I forget as of writing this documentation. It might have been because we didn't want to have a very long URL to make a GET request to but in hindsight it was probably a bad choice.
  • category is either "projects" or "partners", if the field is not supplied it will default to filtering projects
  • If q is the empty string or not supplied, then it will be ignored when filtering for results
  • None of the filter categories are required, if they are not supplied it will not be used when filtering. As a result, if no fields are supplied then it will have the same behavior as GET /users/ or GET /projects/

GET /collaboratorsearch/?q=

Description: If the query parameter q is empty or not supplied all users on the website will be returned. Otherwise, any users with an email that contains the query value will be returned. The user submitting the query will be excluded from the results.

Permissions: IsAuthenticated, user must provide an authentication token.

Parameters/Payload: The query parameter q can be empty or have a value, and it does not have to be supplied.

Example response:

[
  {
    "pk": 1,
    "first_name": "Foo",
    "last_name": "Bar",
    "email": "test@gmail.com"
  },
  ...
]

API Endpoint Permissions

CanEditCollaborators

Collaborators on a project have a property editCollaboratorsPermission. If this property is set to True, then the user making the request is allowed to access the following endpoints:

  • /project/:id/collaborator/add/
  • /project/:id/collaborator/update/
  • /project/:id/collaborator/delete/

The owner of the project has all project related permissions by default.

CanDeleteProject + CanEditProject

Similar to CanEditCollaborators, collaborators on a project have a property deletePermission and editPermission. If this property is set to True, then the user making the request can access the following endpoints respectively:

  • /project/:id/delete/
  • /project/:id/update/

The owner of the project has all project related permissions by default.

IsCollaborator

This permission checks if the user making the request is listed as a collaborator for the specified project. If the user making the request is a collaborator, then they are allowed access to the /project/<int:pk>/togglevisibility/ endpoint. Only collaborators can toggle the visibility of a project on their profile, the project owner will always have the project displayed on their profile.

CanEditDeleteUser

This permission checks if the user making the request is the same as the user being edited. If true, then the user making the request is allowed to access the following endpoints:

  • /user/update/
  • /user/:id/delete/
  • /user/picture/
  • /user/email/
  • /user/preferences/
  • /user/preferences/update/
  • /user/preferences/delete/

isRealUser

This permission checks if the user signing up is a real user using the reCAPTCHA API. Using the reCAPTCHA token generated during signup, it makes a request to the reCAPTCHA API to verify the user. If the API response is true, the user making the request is allowed to access the /rest-auth/registration/ endpoint.

Important note: Because /rest-auth/registration/ is a built in endpoint from the django-rest-auth library, the isRealUser permission was not able to be integrated the standard standard django-reset-framework way. Instead, the line REST_AUTH_REGISTER_PERMISSION_CLASSES = ('api.permissions.isRealUser', 'rest_framework.permissions.AllowAny') had to be added to settings.py for the permission to be integrated into the endpoint. The existence of this setting to configure django-rest-auth was not in their documentation while we were developing PRYDE Connect, and we only discovered it by looking through django-rest-auth's source code.

Clone this wiki locally