stars

Table of Contents

Overview

• Overview

Stars

• List stars by user
• List stars for a specific resource
• List stars across all resources
• Star a resource
• Unstar a resource

Overview

The API exposes a representation of stars that denote user preference for a resource, which can be used to aid in organization and prioritizing of content, especially for display. Users may "star" or "unstar" concepts, similar to how stars function in Gmail. Stars may be used to improve search results through smart sorting if a user is logged in.

Notes

Versioning of stars

• Stars are not versioned

Considerations

• Ideally, it would be possible to actually include the details of a resource if "verbose" is set to true. For example:

GET /orgs/WHO/sources/ICD-10/stars/?verbose=true

{
    "starred_resource_type": "Source",
    "starred_resource_url": "/orgs/WHO/sources/ICD-10/",
    "created_on": "2008-01-14T04:33:35Z",
    "username": "johndoe",
    "source": {
        # Full details of the source are included here, the same as GET /orgs/WHO/sources/ICD-10/
    }
}

• Applying stars to users may not be the best design, as "following" is more the desired behavior.

List stars by user

• Get list of resources starred by user

GET /users/:user/starred/

• Get list of resources starred by the authenticated user

GET /user/starred/

• Parameters
  • resourceType (optional) string - One of the OCL resource types e.g. "Organization", "Source", "Concept", etc.
  • resourceUrl (optional) string - URL of a specific resource e.g. /orgs/WHO/sources/ICD-10/
• Notes
  • "resourceType" and "resourceUrl" parameters may not be used in the same request

Response

• Status: 200 OK

[
    {
        "starred_resource_type": "Concept",
        "starred_resource_url": "/orgs/WHO/sources/ICD-10/concepts/A15.1/",
        "created_on": "2008-01-14T04:33:35Z",
        "username": "johndoe"
    },
    {
        "starred_resource_type": "Source",
        "starred_resource_url": "/orgs/WHO/sources/ICD-10/",
        "created_on": "2008-01-14T04:33:35Z",
        "username": "johndoe"
    }
]

List stars across all resources

• List stars using across all resources and users using the /stars/ endpoint

GET /stars/

• Parameters
  • resourceType (optional) string - One of the OCL resource types e.g. "Organization", "Source", "Concept", etc.
  • resourceUrl (optional) string - URL of a specific resource e.g. /orgs/WHO/sources/ICD-10/
  • username (optional) string
• Notes
  • "resourceType" and "resourceUrl" parameters may not be used in the same request

Response

• Status: 200 OK
• Response is the same format as GET /user/starred/

List stars for a specific resource

• List stars using across all resources and users using the /stars/ endpoint

# orgs
GET /orgs/:org/stars/

# users
GET /users/:user/stars/
GET /user/stars/

# sources
GET /orgs/:org/sources/:source/stars/
GET /users/:user/sources/:source/stars/

# collections
GET /orgs/:org/collections/:collection/stars/
GET /users/:user/collections/:collection/stars/

# concepts
GET /orgs/:org/sources/:source/concepts/:concept/stars/
GET /users/:user/sources/:source/concepts/:concept/stars/

• Parameters
  • username (optional) string

Response

• Status: 200 OK
• Response is the same format as GET /user/starred/

Star a resource

• Star a resource for the authenticated user

POST /user/starred/

• Star a resource for the specified user - Note admin rights are required to use this format

POST /users/:user/starred/

• Input
  • starred_resource_url (optional) string - URL of the resource to star e.g. /orgs/WHO/sources/ICD-10/

{
    "starred_resource_url": "/orgs/WHO/sources/ICD-10/concepts/A15.1/"
}

Response

• Status: 201 Created

{
    "starred_resource_type": "Concept",
    "starred_resource_url": "/orgs/WHO/sources/ICD-10/concepts/A15.1/",
    "created_on": "2008-01-14T04:33:35Z",
    "username": "johndoe"
}

Unstar a resource

• Unstar a resource for the authenticated user

DELETE /user/starred/

• Unstar a resource for the specified user - Note admin rights are required to use this format

DELETE /users/:user/starred/

• Input
  • starred_resource_url (optional) string - URL of the resource to star e.g. /orgs/WHO/sources/ICD-10/

{
    "starred_resource_url": "/orgs/WHO/sources/ICD-10/concepts/A15.1/"
}

Response

• Status: 204 No Content