Re: [Specifications] Adding already existing resources as collection members

Following-up on my ACTION from last telecon, I chose a Vimeo API to review: https://developer.vimeo.com/api/endpoints

Below you can find endpoints relevant to what concerns this issue

---

### Like
https://developer.vimeo.com/api/endpoints/likes

#### Get all videos a user has liked
https://developer.vimeo.com/api/endpoints/likes#GET/users/{user_id}/likes
```
GET https://api.vimeo.com/users/{user_id}/likes
```
eg.
```http
GET /users/elfpavlik/likes
```
```http
HTTP 200 OK
```

#### Like a video
https://developer.vimeo.com/api/endpoints/likes#PUT/users/{user_id}/likes/{video_id}
```
PUT /users/{user_id}/likes/{video_id}
```
eg.
```http
PUT /users/elfpavlik/likes/144522067
```
```http
HTTP 204 No Content
```

#### Unlike a video
https://developer.vimeo.com/api/endpoints/likes#DELETE/users/{user_id}/likes/{video_id}
```
DELETE /users/{user_id}/likes/{video_id}
```
eg.
```http
DELETE /users/elfpavlik/likes/144522067
```
```http
HTTP 204 No Content
```

### Watch Later
* https://developer.vimeo.com/api/endpoints/users#GET/users/{user_id}/watchlater
* https://developer.vimeo.com/api/endpoints/users#PUT/users/{user_id}/watchlater/{video_id}
* https://developer.vimeo.com/api/endpoints/users#DELETE/users/{user_id}/watchlater/{video_id}

### Channels
* https://developer.vimeo.com/api/endpoints/channels#GET/users/{user_id}/channels
* https://developer.vimeo.com/api/endpoints/channels#GET/channels/{channel_id}/users
* https://developer.vimeo.com/api/endpoints/channels#PUT/users/{user_id}/channels/{channel_id}
* https://developer.vimeo.com/api/endpoints/channels#DELETE/users/{user_id}/channels/{channel_id}

---

Some observations:
* It uses a dedicated resource to represent each 'membership' in a list/collection
  * PUT to create new resource representing a 'membership'
  * DELETE to remove existing resource representing a 'membershipt'
* It does NOT follow [URI opacity](https://www.w3.org/TR/webarch/#uri-opacity) good practice
 * client adds '/' and local id of a video to the IRI denoting the collection to create resource representing 'membership' of that video in that collection
* It relies on the server to update the resource representing collection based on operations on resources representing memberships in this collection
 * in case of channels subscriptions it will update both collections, so on `PUT /users/{user_id}/channels/{channel_id}` server will update both
    * `/users/{user_id}/channels`
    * `/channels/{channel_id}/users`


-- 
GitHub Notification of comment by elf-pavlik
Please view or discuss this issue at https://github.com/HydraCG/Specifications/issues/134#issuecomment-333391484 using your GitHub account

Received on Sunday, 1 October 2017 17:13:22 UTC