REST APIs with examples

REST API overview

Ryver provides a REST webservice API that you can use to perform actions such as creating and retrieving content, creating forums and teams, inviting users, and retrieving lists of forums, teams, or users.

API Entity names

Teams are “Workrooms” in the API

In the API examples below, you will see that the teams in Ryver actually have an API entity name of workroom. This is due to the fact that after the 1.0 API was written and released, we changed the name of Private Teams in the UI. They used to be called “workrooms”.

Forums are Forums

Forums were introduced at the same time we renamed workrooms. For all of the team examples below, you can substitute “forum(s)” where you see workroom(s) in the API URLs to perform the same operation on a forum.

Authentication

The Ryver 1.0 REST API uses basic auth currently. We do intend to add OAuth and/or API tokens.

API Headers

For the APIs listed below, you will need the following headers:

On GET requests, you need to include an accept header to indicate that you will accept application/json in the response.

accept: application/json

On POST requests, you will additionally include a content-type header to indicate that you are passing json in the payload.

content-type: application/json

On all requests, you will need to include a basic authentication header, which will look something like this:

authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

TIP: Creating a base64 version of your username:password

To convert your username:password into base64, you can do one of the following:

• Type this into your command prompt: echo -n 'username:password' | base64 . Then copy the resulting string to use with your authentication.
• Use an app like Postman or Paw to insert your username:password into a request header, and then copy the encoded string from there.
• Use an available method like btoa() ( https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa ).
• Write the encoding yourself. (Javascript example: https://scotch.io/tutorials/how-to-encode-and-decode-strings-with-base64-in-javascript .)
• Use an online encoder.

APIs with Examples:

Create Chat Message

Use the workrooms endpoint to post a chat message to a team, and the forums endpoint to post the chat message to a forum.

Use createSource to override the username/avatar in your message.

POST URL: https://example.ryver.com/api/1/odata.svc/workrooms(1000125)/Chat.PostMessage()

curl example:

curl -X "POST" "https://example.ryver.com/api/1/odata.svc/workrooms(1000125)/Chat.PostMessage()" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -u 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
     -d $'{
  "createSource": {
    "avatar": "https://pbs.twimg.com/profile_images/825987046992814080/7VZkFQA9_400x400.jpg",
    "displayName": "Ryver API"
  },
  "body": "This is an example chat message"
}'

Create Topic

In the V1 API, a topic is actually a post. A lot has changed in Ryver since this API was created.

The name isn’t the only thing that goes back to an earlier version of the product. For relating the topic to a specific team, forum or user, you will need to create an outAssociation. Just follow the example and roll with it for now. We’ll have a more straight forward implementation in V2 of the API. Thanks.

To post the topic to a team, set the inType of the outAssociation to Entity.Workroom. For a forum, it will be Entity.Forum. inSecured should always be true, and the inId is the ID of the forum, team or user you are posting the topic to.

POST URL: https://example.ryver.com/api/1/odata.svc/posts

curl example:

curl -X "POST" "https://example.ryver.com/api/1/odata.svc/posts" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -u 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
     -d $'{
  "body": "This is the Topic description",
  "subject": "This is the Topic subject",
  "outAssociations": {
    "results": [
      {
        "inSecured": true,
        "inType": "Entity.Workroom",
        "inId": 1000125
      }
    ]
  },
  "recordType": "note"
}'

Create Task

Note: You need to provide the task board ID, which is different from the team/forum ID.

To get the board ID for a team: https://example.ryver.com/api/1/odata.svc/workrooms(1000125)/board

POST URL: https://example.ryver.com/api/1/odata.svc/tasks

curl example:

curl -X "POST" "https://example.ryver.com/api/1/odata.svc/tasks" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -u 'Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
     -d $'{
  "subject": "This is the task subject that you see in lists and on task cards",
  "body": "The body is what you see in the task description in the UI.",
  "assignees":{
        "results":[{"id":1000192}]
  },
  "category": {
    "id": 1000306
  },
  "board": {
    "id": 1000010
  }
}'

Get team topics

GET URL: https://example.ryver.com/api/1/odata.svc/workrooms(10)/Post.Stream(archived=false)?$format=json

cURL example:

curl -X GET \
'https://example.ryver.com/api/1/odata.svc/workrooms(10)/Post.Stream(archived=false)?$format=json' \
-H 'accept: application/json' \
-H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Additional parameters:

• $top The number of topics you want to display.
  • example: $top=50
• $skip The number of topics (from the top) that you want to skip. Use this to page through topics. Default: none skipped.
  • example: $skip=50
• $inlinecount Include the total number of topics in the response. Default: not included.
  • example: $inlinecount=allpages

Get tasks in a category

GET URL: https://example.ryver.com/api/1/odata.svc/taskCategories(1)/tasks

cURL example:

curl -X GET \
'https://example.ryver.com/api/1/odata.svc/taskCategories(1)/tasks' \
-H 'accept: application/json' \
-H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Additional parameters:

• $top The number of tasks you want to display.
  • example: $top=50
• $skip The number of tasks (from the top) that you want to skip. Default: none skipped.
  • example: $skip=50
• $inlinecount Include the total number of tasks in the response. Default: not included.
  • example: $inlinecount=allpages
• $select Use this to filter your results by specific properties.
  • example: $select=id,subject,body,modifyDate,createDate,dueDate,completeDate,short,attachmentsCount,commentsCount

Get all tasks in a task board

GET URL: https://example.ryver.com/api/1/odata.svc/workrooms(10)/TaskBoard.Get()

Get a task board ID using team ID

GET URL: https://example.ryver.com/api/1/odata.svc/workrooms(10)/board?$select=id

cURL example:

curl -X GET \
'https://example.ryver.com/api/1/odata.svc/workrooms(10)/board?$select=id' \
-H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Get a category id from team task board

GET URL: https://example.ryver.com/api/1/odata.svc/taskBoards(10)/categories?$select=id,name

cURL example:

curl -X GET \
'https://example.ryver.com/api/1/odata.svc/taskBoards(10)/categories?$select=id,name' \
-H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Create team

POST URL: https://example.ryver.com/api/1/odata.svc/workrooms

JSON payload: {"name":"Example","about":"example","description":"example", "nickname":"example"}

cURL example:

curl -X POST \
  https://example.ryver.com/api/1/odata.svc/workrooms \
  -H 'accept: application/json' \
  -H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  -H 'content-type: application/json' \
  -d '{"name":"Example","about":"example","description":"example", "nickname":"example"}'

Add existing user to team

POST URL: https://example.ryver.com/api/1/odata.svc/users(1)/User.AddToTeams()

JSON payload: {"teams":[{"id":10,"role":"ROLE_TEAM_MEMBER"}]}

cURL example:

curl -X POST \
  https://example.ryver.com/api/1/odata.svc/users(1)/User.AddToTeams() \
  -H 'accept: application/json' \
  -H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  -H 'content-type: application/json' \
  -d '{"teams":[{"id":10,"role":"ROLE_TEAM_MEMBER"}]}'

Add a new user to team

You can use the Invite User API to add a new user to one or more teams. You can optionally include username and/or displayName properties, in addition to email, to pre-populate those values in the User Profile page that the person is asked to fill out when they accept their invite.

Note: If the email address matches an existing user, it will add that user, not send an invite.

POST URL: https://example.ryver.com/api/1/odata.svc/User.Invite()

JSON payload: {"email":"name@example.com","teams":[{"id":10,"role":"ROLE_TEAM_MEMBER"}],"type":"member"}

cURL example:

curl -X POST \
  https://example.ryver.com/api/1/odata.svc/User.Invite() \
  -H 'accept: application/json' \
  -H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  -H 'content-type: application/json' \
  -d '{"email":"name@example.com","teams":[{"id":10,"role":"ROLE_TEAM_MEMBER"}],"type":"member"}'

Get team members and roles

The workrooms/members API call actually returns the values in a join table between workrooms (teams) and users, with the join table containing the role of the user on this team. The workroomMembers collection that this API returns contains a member object property that represents the actual user. We will use the select parameter to return a specific set of properties, and the exapand parameter to access the properties of the member object:

GET URL: https://example.ryver.com/api/1/odata.svc/workrooms(10)/members?$select=role, member/id, member/username&$expand=member

cURL example:

curl -X GET \
'https://example.ryver.com/api/1/odata.svc/workrooms(10)/members?$select=role, member/id, member/username&$expand=member' \
-H 'accept: application/json' \
-H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Additional parameters:

• $top The number of team members you want to display.
  • example: $top=50
• $skip The number of team members (from the top) that you want to skip. Default: none skipped.
  • example: $skip=50
• $inlinecount Include the total number of members in the response. Default: not included.
  • example: $inlinecount=allpages
• $select Use this to filter your results by specific properties.
  • example: $select=id,roles,extras,__descriptor
• expand Use this parameter to include the properties of specified object properties that are included in the query results.
  • example: $expand=member

Remove user from team

For this API call, you need to know the workroomMember ID for the join record that associates the user with the team (see Get team members and roles above)

POST URL: https://example.ryver.com/api/1/odata.svc/workroomMembers(1000)/Remove()

Set user role on team

Once again, you need to know the workroomMember ID for this API call (see Get team members and roles above)

POST URL: https://example.ryver.com/api/1/odata.svc/workroomMembers(1000)/Role.Set(role='ROLE_TEAM_ADMIN')

Get list of teams or forums

To get a list of teams, you need to use the “workrooms” endpoint, due to teams having used to be called workrooms:

GET URL: https://example.ryver.com/api/1/odata.svc/workrooms

Forums actually have a more direct API:

GET URL: https://example.ryver.com/api/1/odata.svc/forums

Additional parameters:

• $top The number of users you want to display.
  • example: $top=50
• $skip The number of users (from the top) that you want to skip. Default: none skipped.
  • example: $skip=50
• $inlinecount Include the total number of users in the response. Default: not included.
  • example: $inlinecount=allpages
• $select Use this to filter your results by specific properties.
  • example: $select=id,name,nickname,description

Get organization users

GET URL: https://example.ryver.com/api/1/odata.svc/users

cURL example:

curl -X GET \
'https://example.ryver.com/api/1/odata.svc/users' \
-H 'accept: application/json' \
-H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='

Additional parameters:

• $top The number of users you want to display.
  • example: $top=50
• $skip The number of users (from the top) that you want to skip. Default: none skipped.
  • example: $skip=50
• $inlinecount Include the total number of users in the response. Default: not included.
  • example: $inlinecount=allpages
• $select Use this to filter your results by specific properties.
  • example: $select=id,username,displayName,emailAddress

Invite user to organization

** Requires Admin User Credentials **

The User.Invite() API allows you to invite a new guest or member user (indicate which one with the type property). You can also specify one or more teams and forums you would like the user to be automatically joined to. The teams property can contain a combination of teams and forums in this API.

You can optionally include username and/or displayName properties to pre-populate those values in the User Profile page that the person is asked to fill out when they accept their invite.

Note: If the email address matches an existing user, it will add that user, not send an invite.

POST URL: https://example.ryver.com/api/1/odata.svc/User.Invite()

JSON payload: {"email":"name@example.com","teams":[{"id":10,"role":"ROLE_TEAM_MEMBER"}],"type":"member"}

cURL example:

curl -X POST \
  https://example.ryver.com/api/1/odata.svc/User.Invite() \
  -H 'accept: application/json' \
  -H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  -H 'content-type: application/json' \
  -d '{"email":"name@example.com","teams":[{"id":10,"role":"ROLE_TEAM_MEMBER"}],"type":"member"}'

Deactivate user

** Requires Admin User Credentials **

POST URL: https://example.ryver.com/api/1/odata.svc/users(id=1000000)/User.Active.Set(value='false')

cURL example:

curl -X POST \
  https://example.ryver.com/api/1/odata.svc/users(id=1000000)/User.Active.Set(value='false') \
  -H 'accept: application/json' \
  -H 'authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  -H 'content-type: application/json'