diff --git a/README.md b/README.md index f184bb8..6e8e24c 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,52 @@ The UNIWeb API allows institutions to seamlessly integrate UNIWeb with their exi - **Flexible Filtering**: Query specific data subsets to optimize response times - **Reference Implementation**: PHP client library with example use cases -## Quick Start +## Implementation Options -### Installation Options +### 1. Simple Integration + +Before implementing the API, consider if you just need to embed UNIWeb content. You can use the embed parameter: + +```html + +``` + +### 2. Using Postman or Direct HTTP Requests + +The simplest way to test and use the API is through direct HTTP requests. Here are some common examples: + +```bash +# Get user profile information +GET {{BASE_API_URL}}/resource.php?action=read + &resources[]=profile/affiliations + &resources[]=profile/membership_information + &id=833 + +# Get members by unit and title +GET {{BASE_API_URL}}/resource.php?action=read + &resources[]=profile/affiliations + &resources[]=profile/membership_information + &filter[unit]=University of XYZ + &filter[title]=Professor + +# Get all members +GET {{BASE_API_URL}}/resource.php?action=getMembers&onlyPublic=0 + +# Get profile picture +GET {{BASE_API_URL}}/picture.php?action=display + &contentType=members + &id=833 + &quality=large +``` + +### 3. Using the PHP Client + +Begin by installing [PHP Composer](https://getcomposer.org/download/) if you don't already have it. #### Option 1: Create a New Project (Recommended for Testing) @@ -26,7 +69,7 @@ The UNIWeb API allows institutions to seamlessly integrate UNIWeb with their exi # Creates a new project with example code and CLI testing tools composer create-project proximify/uniweb-api -# Optional: specify custom installation path +# Optional: specify custom installation name or path composer create-project proximify/uniweb-api my-test ``` @@ -47,15 +90,18 @@ composer require proximify/uniweb-api 4. Enter a client name and save 5. Click "View" on your new client to reveal the secret key +> [!TIP] +> Review the Profile and CV data schemas located at Administration → Schemas + ### 2. Configure Credentials Create `settings/credentials.json`: ```json { - "clientName": "your_client_name", - "clientSecret": "your_client_secret", - "homepage": "your_uniweb_instance_url" + "clientName": "your_client_name", + "clientSecret": "your_client_secret", + "homepage": "your_uniweb_instance_url" } ``` @@ -100,14 +146,90 @@ For detailed API documentation, see [Complete UNIWeb API Documentation](docs/uni ## Sample Use Cases The `queries` folder contains example code for common API operations: + - Fetching user profiles - Updating research activities - Retrieving publication data - And more... +## Resource Paths + +Resources are identified by paths following this structure: + +``` +page/section/subsection/... +``` + +Example paths: + +- `profile/affiliations` +- `cv/education/degrees` +- `profile/membership_information` + +### Content Types + +- `members`: Individual user data +- `units`: Organizational unit data +- `groups`: Group-related data + +## Common Operations + +### Reading Data + +Send as GET or POST parameters. + +```json +{ + "action": "read", + "content": "members", + "filter": { + "unit": "Civil Engineering" + }, + "resources": ["profile/biography"] +} +``` + +### Filtering Options + +- `unit`: Filter by department/unit +- `title`: Filter by title (e.g., "Professor") +- `loginName`: Filter by username/email +- `modified_since`: Filter by modification date +- `onlyPublic`: Include/exclude private data + +### Language Support + +Add `language` parameter: + +- `en`: English responses +- `fr`: French responses + +## Error Handling + +Errors are returned in JSON format: + +```json +{ + "error": { + "message": "Error description", + "type": "ErrorType", + "code": 98, + "error_subcode": 223 + } +} +``` + +Common error codes: + +- 98: OAuth token validation error +- 401: Unauthorized +- 403: Insufficient permissions +- 404: Resource not found + ## API Capabilities The UNIWeb API provides: + - Secure authentication - User data management - Research activity tracking @@ -118,6 +240,7 @@ The UNIWeb API provides: ## Support For technical questions or issues: + 1. Check the [API Documentation](docs/uniweb-api.md) 2. Create an issue in this repository 3. Contact UNIWeb support through your institutional channels diff --git a/docs/uniweb-api.md b/docs/uniweb-api.md index e483d46..e220d05 100644 --- a/docs/uniweb-api.md +++ b/docs/uniweb-api.md @@ -4,15 +4,18 @@ # UNIWeb API -## Preamble +## Quick Note: Simple Integration -Before you spend time reading about the UNIWeb API, it is important to determine whether you need the API at all. There are some scenarios that can be resolved with the API, but that can also be resolved in a simpler way. One such case is the embedding of UNIWeb pages into an institutional website. UNIWeb pages allow for a special parameter to signal that the page will be embedded. +Before implementing the API, consider if you just need to embed UNIWeb content. You can use the embed parameter: -
-
-
- -The ?embed=1 part of the URI tells UNIWeb to only show the **main** content of the page and hide everything else. With this approach, user profiles and other pages can easily be reused in different contexts within an institutional website. +```html + +``` ## API Overview @@ -20,10 +23,10 @@ The purpose of the API is to integrate UNIWeb with other systems within your org The UNIWeb API provides: -- An interface that allows you to control who has access to your institution's data through our API. -- A means by which to securely read and update your institution's information. -- Rich data in simple, straightforward JSON for maximum readability and reusability. -- The choice to pre-filter the requested data, to obtain just the subset of information in which you are interested. +- An interface that allows you to control who has access to your institution's data through our API. +- A means by which to securely read and update your institution's information. +- Rich data in simple, straightforward JSON for maximum readability and reusability. +- The choice to pre-filter the requested data, to obtain just the subset of information in which you are interested. The UNIWeb API uses [Internet Engineering Task Force (IETF)](http://www.ietf.org/) open authentication standard [OAuth 2.0](http://oauth.net/2/), for authentication and authorization using the [Resource Owner Password Credentials Grant protocol](http://tools.ietf.org/html/rfc6749#section-4.3). In this protocol, only users with granted permission can access the API. @@ -72,7 +75,7 @@ With the client credentials obtained in step 3, you can authenticate to the UNIW With these pieces of information you will be allowed to make API requests. To do so, you can use one of our pre-built client libraries -- [PHP client lib](../README.md) +- [PHP client lib](../README.md) #### 4. Access information through structured requests @@ -82,12 +85,12 @@ Example request object: ```json { - "action": "read", - "content": "members", - "filter": { - "loginName": "bob@mail.ca" - }, - "resource": ["profile/biography", "profile/selected_degrees"] + "action": "read", + "content": "members", + "filter": { + "loginName": "bob@mail.ca" + }, + "resource": ["profile/biography", "profile/selected_degrees"] } ``` @@ -95,20 +98,20 @@ Example response for the above request: ```json { - "bob@mail.ca": { - "profile/biography": "Bob always knew he would be a great scientist", - "profile/selected_degrees": [ - { - "degree_name": "PhD", - "organization": "McGill University", - "specialty": "Materials Engineering" - }, - { - "degree_name": "Engineering", - "organization": "University of Ottawa" - } - ] - } + "bob@mail.ca": { + "profile/biography": "Bob always knew he would be a great scientist", + "profile/selected_degrees": [ + { + "degree_name": "PhD", + "organization": "McGill University", + "specialty": "Materials Engineering" + }, + { + "degree_name": "Engineering", + "organization": "University of Ottawa" + } + ] + } } ``` @@ -139,7 +142,7 @@ Optionally, a request path can be specified as a JSON object. In particular, thi ```json { - "page/section/section/section/...": ["field name A", "field name B", "..."] + "page/section/section/section/...": ["field name A", "field name B", "..."] } ``` @@ -504,12 +507,12 @@ The request that follows would return the public profile information of all peop ```json { - "action": "read", - "content": "members", - "filter": { - "unit": "Civil Engineering" - }, - "resources": "profile" + "action": "read", + "content": "members", + "filter": { + "unit": "Civil Engineering" + }, + "resources": "profile" } ``` @@ -522,24 +525,20 @@ The request that follows would return two resources belonging to the user with l ```json { - "action": "read", - "content": "members", - "language": "fr", - "filter": { - "unit": "McGill", - "title": "Professor", - "login": "john@smith.ca" - }, - "resources": [ - "profile/research_interests", - { - "cv/education/degrees": [ - "degree_name", - "specialization", - "thesis_title" - ] - } - ] + "action": "read", + "content": "members", + "language": "fr", + "filter": { + "unit": "McGill", + "title": "Professor", + "login": "john@smith.ca" + }, + "resources": [ + "profile/research_interests", + { + "cv/education/degrees": ["degree_name", "specialization", "thesis_title"] + } + ] } ``` @@ -551,11 +550,11 @@ Errors will give information about what went wrong with a corresponding request. ```json { - "error": { - "message": "Error validating access token.", - "type": "OAuthException", - "code": 98, - "error_subcode": 223 - } + "error": { + "message": "Error validating access token.", + "type": "OAuthException", + "code": 98, + "error_subcode": 223 + } } ```