swagger: '2.0' info: version: "1.0.0" description: | Campus Data offers an API to allow developers to query data items and related information for a Campus Data team. To use the API, a client must use BasicAuth to provide credentials that are issued by Campus Data. The credentials are tied to a specified team, and results from the API are limited to artifacts owned by the team. Please use the contact link below to request credentials. In special circumstances, credentials can be issued that will allow developers to pull data from multiple teams. These credentials can only be created by Campus Data administrators, and the usage must be approved by all team administrators. title: Campus Data contact: email: campus-data@uiowa.edu basePath: /api/v1 schemes: - https securityDefinitions: basicAuth: type: basic description: HTTP Basic Authentication. Works only over `HTTPS` tags: - name: team description: Everything about Teams - name: item description: Everything about Data Items - name: request description: Everything about Requests # - name: member # description: Everything about Team Members # - name: explorer # description: Explorer renders HTML views of Data Items in catalog for authenticated users. Includes helper functions for driving filters. paths: /team: get: summary: Returns details about a Team. description: Returns a `Team` object. produces: - application/json tags: - team security: - basicAuth: [] responses: 200: description: Successful response schema: $ref: "#/definitions/Team" /team/items: get: summary: Returns a `ItemSearchResult` object containing a list of `DataItem` objects. description: Returns a `ItemSearchResult` object containing a list of `DataItem` objects owned by the authorized team. The items can be restricted to those accessible to a particular user by providing the user param. The items may also be filtered by a number of attributes detailed in the parameters below. produces: - application/json tags: - team security: - basicAuth: [] parameters: - $ref: "#/parameters/userParam" - $ref: "#/parameters/statusParam" - $ref: "#/parameters/formatParam" - $ref: "#/parameters/topicParam" - $ref: "#/parameters/tagParam" - $ref: "#/parameters/tagOperatorParam" - $ref: "#/parameters/sortParam" - $ref: "#/parameters/sortDirectionParam" - $ref: "#/parameters/pageNumberParam" - $ref: "#/parameters/pageSizeParam" responses: 200: description: Successful response schema: title: ArrayOfDataItems type: array items: $ref: "#/definitions/DataItem" /team/requests: get: summary: Fetch outstanding requests for a Team. description: Returns an array of outstanding `Request` objects that are currently assigned to the Team. produces: - application/json tags: - team - request security: - basicAuth: [] responses: 200: description: Successful response schema: title: ArrayofRequests type: array items: $ref: "#/definitions/Request" /team/members: get: summary: Fetch the members of a team. description: Returns an array of `Member` objects that are assigned to the Team. produces: - application/json tags: - team security: - basicAuth: [] responses: 200: description: Succesful response schema: title: ArrayofMembers type: array items: $ref: "#/definitions/Member" /team/topics: get: summary: Fetch the topics associated with the credentialed team's published items. description: Returns an array of `DataTopic` objects that are associated with the credentialed team's published items. produces: - application/json tags: - team security: - basicAuth: [] responses: 200: description: Succesful response schema: title: ArrayofTopics type: array items: $ref: "#/definitions/DataTopic" /teams: get: summary: Returns a `TeamSearchResult` object containing a list of `Team` objects. description: Returns a `TeamSearchResult` object containing a list of `Team` objects. With a standard API credential, this endpoint will return details of the team that owns the credential and effectively duplicates the `/team` endpoint. When used with an API credential with the TEAMS scope, this endpoint will return details for the teams tied to the credential. This type of credential can only be issued by Campus Data administrators. produces: - application/json tags: - team security: - basicAuth: [] responses: 200: description: Successful response schema: $ref: "#/definitions/Team" /items: get: summary: Returns a `ItemSearchResult` object containing a list of `DataItem` objects. description: Returns a `ItemSearchResult` object containing a list of `DataItem` objects. Search results can be filtered using the paramerters below. produces: - application/json tags: - item security: - basicAuth: [] parameters: - $ref: "#/parameters/userParam" - $ref: "#/parameters/teamParam" - $ref: "#/parameters/statusParam" - $ref: "#/parameters/formatParam" - $ref: "#/parameters/topicParam" - $ref: "#/parameters/tagParam" - $ref: "#/parameters/tagOperatorParam" - $ref: "#/parameters/sortParam" - $ref: "#/parameters/sortDirectionParam" - $ref: "#/parameters/pageNumberParam" - $ref: "#/parameters/pageSizeParam" responses: 200: description: Successful response schema: $ref: "#/definitions/DataItem" 403: description: API key does not have permission to that Data Item 404: description: Data Item not found /items/{id}: get: summary: Returns details about a Data Item. description: Returns a `DataItem` object produces: - application/json tags: - item security: - basicAuth: [] parameters: - name: id in: path description: ID of Data Item required: true type: integer format: int64 responses: 200: description: Successful response schema: $ref: "#/definitions/DataItem" 403: description: API key does not have permission to that Data Item 404: description: Data Item not found /items/access: get: summary: Returns access details for a particular user and data item. description: This endpoint describes a user's access rights to a specified data item. Either an item id or url must be provided along with the user's hawkid. Returns an `AccessReceipt` object. If either a user or a data item is not found, a 404 will be returned. produces: - application/json tags: - item security: - basicAuth: [] parameters: - name: hawkid in: query description: HawkId of the user seeking access to the item. required: true type: string - name: id in: query description: Id of a data item. required: false type: string - name: url in: query description: Url of a data item. required: false type: string responses: 200: description: Successful response schema: $ref: "#/definitions/AccessReceipt" 404: description: Data Item or user not found /items/formats: get: summary: Fetch the valid formats for use when exploring Data Items. description: Return an array of valid formats for Data Items produces: - application/json tags: - item security: - basicAuth: [] responses: 200: description: Successful response schema: title: ArrayofDataFormat type: array items: $ref: "#/definitions/DataFormat" /items/topics: get: summary: Fetch the appropriate data topics for exploring Data Items. description: Return an array of `DataTopic` objects for browsing Data Items. For standard credentials, all topics will be returned. For an API credential configured for a list of teams, the resulting list will be filtered to topics associated to the credentialed teams' published items. If a team id is provided through a query parameter, results will be filtered to topics related to the specified team. produces: - application/json tags: - item security: - basicAuth: [] parameters: - name: team in: query description: Id of team to use as topic filter. required: false type: string responses: 200: description: Successful response schema: title: ArrayofDataTopic type: array items: $ref: "#/definitions/DataTopic" /items/sorts: get: summary: Fetch the valid sort types for Data Items. description: Return an array of valid sorts for Data Items produces: - application/json tags: - item security: - basicAuth: [] responses: 200: description: Successful response schema: title: ArrayofDataSort type: array items: $ref: "#/definitions/DataSort" /items/tags: get: summary: Fetch information about Tags associated with Data Items. description: Return an array of Tags produces: - application/json tags: - item security: - basicAuth: [] responses: 200: description: Successful response schema: title: ArrayofItemTag type: array items: $ref: "#/definitions/ItemTag" /requests/{key}: get: summary: Returns details about a Request description: Returns a `Request` object produces: - application/json tags: - request security: - basicAuth: [] parameters: - name: key in: path description: Key of the Request required: true type: string responses: 200: description: Successful response schema: $ref: "#/definitions/Request" 403: description: API key does not have permission to that Request 404: description: Request not found # /explorer: # get: # summary: Returns HTML view of explorer # description: Returns a HTML view of the explorer from which you can pass in filters. Uses HawkID login (UIP) authentication. # produces: # - text/html # tags: # - explorer # parameters: # - name: topic # in: query # description: The name of the topic you would like to filter by - See /items/topics to get valid options # required: false # type: string # enum: ## - ACADEMICS ## - ADVANCEMENT ## - COURSES ## - DEVICES ## - ENROLLMENT ## - FACILITIES ## - FINANCIAL_AID ## - FINANCIALS ## - HR ## - IDENTITY ## - IT ## - LIBRARIES ## - RESEARCH ## - MULTI ## - UNCATEGORIZED ## - name: team # in: query # description: The team ID you would like to filter by - See /explorer/teams to get valid options # required: false # type: integer # format: int64 # - name: tag # in: query # description: The tag you would like to filter by - See /items/tags to get valid options # required: false # type: string # - name: format # in: query # description: The name of the format of the Data Item you would like to filter by - See /explorer/formats to get valid options # required: false # type: string # enum: ## - API ## - ARTICLE ## - COLLECTION ## - CUBE ## - DASHBOARD ## - DATASET ## - MAUI ## - PORTAL ## - REPORT ## - SURVEY ## - UI_WAREHOUSE ## - VISUALIZATION ## - WEB ## responses: # 200: # description: Successful response # # /explorer/teams: # get: # summary: Fetchs the valid teams for explorer Data Items # description: Return an array of valid Teams for Data Items # produces: # - application/json # tags: # - explorer # responses: # 200: # description: Successful response # schema: # title: ArrayofTeam # type: array # items: # $ref: "#/definitions/Team" # Data item filter parameters parameters: userParam: name: user in: query description: Hawkid of a user. Limit results to items accessible to the user. required: false type: string teamParam: name: team in: query description: Id of a Campus Data team. Limit results to the specified team. required: false type: integer statusParam: name: status in: query description: Filter results to items with the provided status. required: false type: string formatParam: name: format in: query description: Filter results to items with the provided format. required: false type: string topicParam: name: topic in: query description: Filter results to items with the provided topic. required: false type: string tagParam: name: tag in: query description: Comma delimited list of tags. Filter results to items with either all the tags or one or more of the tags depending on the tag operator (`top` parameter). The tag operator defaults to AND. required: false type: string tagOperatorParam: name: top in: query required: false schema: type: string enum: [OR, AND] default: AND description: > Tag operator: * 'AND' - Match all of the supplied tags * 'OR' - Match one or more of the supplied tags sortParam: name: sort in: query required: false schema: type: string default: name description: Sort results by the provided attribute. sortDirectionParam: name: dir in: query required: false schema: type: string enum: [ASC, DESC] default: ASC description: Sort results in the provided direction. pageNumberParam: name: pager.page description: Page number for paged results in: query required: false type: integer pageSizeParam: name: pager.size description: Page size for paged results in: query required: false type: integer definitions: DataItem: type: object properties: id: type: integer format: int64 description: the id of the Data Item name: type: string description: The name of the Data Item description: type: string description: The long description of the Data Item url: type: string description: A Campus Data url that will record access metrics and forward the user on to the registered url. Clients should use the tracking url if at all possible. url is the same as trackingUrl. trackingUrl: type: string description: A Campus Data url that will record access metrics and forward the user on to the registered url registeredUrl: type: string description: The registered url to the report or attachment on the Data Item metaUrl: type: string description: A url back to Campus Data that will show the description and documentation of the Data Item access: type: string description: The level of access required to access the Data Item - PRIVATE = This data is private.; PUBLIC = This data is available to the public.; TEAM = This data is available to team members.; AUTHENTICATED = This data is available to all of campus (anyone who can log in).; AUTHORIZED = This data is available to team members and campus users according to the established security rules. type: type: string description: The type of Data Item - API, Article, Collection, Cube, Dashboard, Dataset, Portal, Report, MAUI, Web, Survey, UI Warehouse, Visualization topic: type: string description: The topic of the data item - Academics, Advancement, Course Management, Device Management, Enrollment Management, Facilities Management, Financial Aid, Financials, Human Resources, Identity (People and Organizations), Information Technology, Libraries, Research, Multi-Topic, Uncategorized tags: type: string description: The tags assigned to the Data Item. team: type: string description: The Team that owns the Data Item. updatedOn: type: string format: date-time description: The timestamp the Data Item was last updated required: - id - name - access - type - updatedOn DataTopic: type: object properties: name: type: string description: The name of the Topic label: type: string description: The descriptive label of the Topic required: - name - label DataFormat: type: object properties: name: type: string description: The name of the Format label: type: string description: The descriptive label of the Format required: - name - label DataSort: type: object properties: param: type: string description: Value to use with sort query parameter direction: schema: type: string enum: [ASC, DESC] default: ASC label: type: string description: Label describing the type of sort ItemTag: type: object properties: tag: type: string description: The name of the tag usage: type: integer format: int64 description: The number of DataItems that are associated with this tag required: - tag - usage Team: type: object properties: id: type: integer format: int64 description: The id of the Team name: type: string description: The name of the Team contact: type: string description: The email address of the team contact description: type: string description: A short description of the Team icon: type: string description: URl of the team's icon website: type: string description: URL of the team's website campusOk: type: boolean description: The team can publish Data Items to campus isPublished: type: boolean description: The team is visible in searches and exploration isActive: type: boolean description: The team is active and all published Data Items are available updatedOn: type: string format: date-time description: The timestamp the Team was last updated required: - id - name - campusOk - isPublished - isActive - updatedOn Request: type: object properties: key: type: string description: The unique key identifying the Request description: type: string description: A short description of the Request topic: type: string description: The topic for the Request - Support, Security, Question, Feature, Other, Data Access, Bug Report, Data, Finding Data, Data Conflict, Data Team, Kudos status: type: string description: The current status of the Request - Open, Under Review, Need Feedback, Needs Attention, Workflow, Workflow Complete, Closed, Deleted team: type: string description: The team the request is currently assigned to user: type: string description: The HawkId of the user that created the Request createdOn: type: string format: date-time description: The timestamp the Request was created updatedOn: type: string format: date-time description: The timestamp the Request was last updated comments: type: array items: $ref: "#/definitions/RequestComment" required: - key - description - status - team - createdOn - updatedOn RequestComment: type: object properties: id: type: integer format: int64 description: The id of the RequestComment content: type: string description: The body of the comment user: type: string description: The HawkId of the user who created the RequestComment createdOn: type: string format: date-time description: The timestamp the RequestComment was created required: - id - content - user - createdOn Member: type: object properties: id: type: integer format: int64 description: The id of the Member hawkid: type: string description: The HawkId of the Member name: type: string description: The last name, first name of the Member roles: type: array description: The Role(s) assigned to the Member - Member, Support, Developer, Publisher, Approver, Steward, Admin items: type: string createdOn: type: string format: date-time description: The timestamp the Member was created updatedOn: type: string format: date-time description: The timestamp the Member was last updated required: - id - hawkid - name - createdOn - updatedOn - roles AccessReceipt: type: object properties: item: type: integer format: int64 description: The id of the Data Item hawkid: type: string description: The HawkId of the User accessible: type: boolean description: Flag indicating if the user can access the item or not discoverable: type: boolean description: Flag indicating if the item appears in results for users who do not have access required: - item - hawkid - accessible - discoverable - validItem - validUser ItemSearchResult: type: object properties: results: type: array description: List of search results items: $ref: "#/definitions/DataItem" size: type: integer description: Number of results returned in the response total: type: integer description: Total number of search results sort: type: object properties: criteria: type: string description: Criteria used to sort the results dir: type: string description: Direction used to sort the results paged: type: boolean description: Flag indicating whether the results were paged or not pager: type: object properties: page: type: integer description: Page number in paged results set size: type: integer description: Page size in paged results set TeamSearchResult: type: object properties: results: type: array description: List of search results items: $ref: "#/definitions/Team" size: type: integer description: Number of results returned in the response total: type: integer description: Total number of search results sort: type: object properties: criteria: type: string description: Criteria used to sort the results dir: type: string description: Direction used to sort the results paged: type: boolean description: Flag indicating whether the results were paged or not pager: type: object properties: page: type: integer description: Page number in paged results set size: type: integer description: Page size in paged results set