Zyncro rest api feb 2013


Published on

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Zyncro rest api feb 2013

  1. 1. Social Networks Your Enterprise Social Network For Enterprises Developing using the REST API1
  2. 2. Agenda REST API overview REST API services OAuth authorization Let’s play with the API REST API entities PHP API client2
  3. 3. REST API overview The REST API gives you access to the most of the features you see in our web app and lets you extend them for use in your own app. It strives to be RESTful and is organized around the main resources you’re familiar with from the Zyncro web interface. Use our REST API to create applications and web sites that natively integrate with Zyncro The REST API is a collection of web services, which means that you can create Zyncro applications using any modern programming language and operating system on any computer connected to the Internet. OAuth 1.0a protocol is used to provide authorized access to our REST API services. HTTP REST services use JSON format in their responses.3
  4. 4. REST API overview You access a resource by sending an HTTPS request to the Zyncro API server. The server replies with a response that either contains the data you requested, or a status indicator, or both. The format of the URL to access the API is, for example, https://my.sandbox.zyncro.com/api/v1/rest HTTP methods separate API actions GET is used to retrieve a representation (or, "stuff") from a resource or a collection of resources. POST is used to create or modify a representation of a resource (we do not use PUT). DELETE is used to remove the information about a resource.4
  5. 5. REST API overview HTTP status code in responses: 200 The request was successfully received, understood, and accepted. 4xx An error in the request. Usually a bad parameter. 5xx The request is fine, but something is wrong on Zyncro’s end. Our REST API is split up into different areas, which contain a subset of services grouped by functionality.5
  6. 6. REST API - Use We are using the REST API, for example, in these integrations and native apps6
  7. 7. Play with REST API Show me the money! http://apidocs.sandbox.zyncro.com/7
  8. 8. REST API services • Manage the organization configuration Organization services • Manage organizations users (add/edit/remove) /api/v1/rest/organization • Edit organization properties • Only admin users can have access to these services • Manage user profiles Users services • Access follower/following user lists /api/v1/rest/users • Edit user profile, change user’s profile image • Follow/Unfollow users Microblogging and Activity • Access and publish in all microblogging, including Stream & Inbox services Personal feed, Corporate feed, Department feeds, Private messages and Messages from Groups /api/v1/rest/wall • Access users inbox events and notifications • Create new groups Groups services • Download, edit, and upload documents to groups /api/v1/rest/groups • Manage group members, folders and files • Join/leave open groups8
  9. 9. REST API services • Create new departments Departments services • Download, edit, upload documents in departments /api/v1/rest/departments • Manage department members, folders and files • Follow/unfollow departments • Manage invitations. Invitations services • Send, accept, decline invitations /api/v1/rest/invitations • Access the list of pending invitations • Create new tasks. Tasks services • Edit task and access to the tasks of groups /api/v1/rest/tasks • Access to the list of tasks ZyncroApps Services • Manage apps (add/edit/remove) /api/v1/rest/apps • Enable/disable apps9
  10. 10. OAuth authorization - REST API 1) Get a Request Token 2) A User have to authorize the Request Token 3) Exchange the authorized Request Token for an Access Token 4) Use the Access Token to invoke REST API services10
  11. 11. OAuth types in REST API We have three ways of getting an Access Token to invoke REST API services Web browser authorization Get a Request token Authenticate the user using a Zyncro login web page Get an Access token External service authorization Get a Request token Authenticate the user using an external service Get an Access token ZyncroApp authorization Use combined with ZyncroApps when the user is already logged in Zyncro. We’ll see it while seeing ZyncroApps development. Examples soon to come!11
  12. 12. Java sample - REST API Sample showing how to get the profile of a User using the REST API public final static String API_KEY = ... public static final String API_SECRET = ... public final static String ACCESS_KEY = ... public final static String ACCESS_SECRET = ... OAuthService service = new ServiceBuilder() .provider(ZyncroApi.class) .apiKey(Paths.API_KEY) .apiSecret(Paths.API_SECRET) .build(); OAuthRequest request = new OAuthRequest( Verb.GET, "https://my.sandbox.zyncro.com/api/v1/rest/users/profile"); Token accessToken = new Token(Paths.ACCESS_KEY, Paths.ACCESS_SECRET); service.signRequest(accessToken, request); Response response = request.send(); ...12
  13. 13. JSON response sample - REST API {"object":{ "appId":"francoscavuzzo-6387", "fullName":"Franco Scavuzzo", "email":"franco@zyncro.com", "name":"Franco", "lastname":"Scavuzzo", "organizationName":"Zyncro Tech, S.L.", "since":"1283158384316", "isFollowing":false, "isFollowedBy":false, "isFollowingActivity":false, "isFollowedActivityBy":false, "language":"en", "organizationUrn":"syncrum:domain:24078705-7041-4a45-ad1d-32fe4d60ee69", "companyFeedUrn":"syncrum:sharegroup:63e82dde-885b-4f0d-b6b0-8bdcc50ca3c7", "personalFeedUrn":"syncrum:sharegroup:67c4b5c6-f113-4e6c-ac89-ba76993f9388", "personalFilesGroupUrn":"syncrum:sharegroup:379ef9fc-ed31-49ad-9d3d-d2141e68cd4c", "userStatusInfo":{"userStatus":0,"message":"Trabajando","date":"1354527495871"}, …. "canCreateDepartments":false, "isOrganizationAdmin":true, "storageOccupied":"143225271", "storageAssigned":"1048576000", },"result":"OK“}13
  14. 14. Play with REST API Let’s play with the REST API http://apidocs.sandbox.zyncro.com/ Demo14
  15. 15. REST API entities Event Inbox Event Group Department Member User15
  16. 16. REST API entities Organization Invitation Task Document Document App Version16
  17. 17. REST API entities • All the main entities in API have a unique identifier, normally call URN (unique resource identifier) • For the attributes that represent date and time, we use UNIX epoch representation in milliseconds17
  18. 18. REST API entities An Event represents an activity that has occurred in Zyncro, for example: a user has published a new message, a document has been changed, a new group has been created… Some of the important attributes related with an Event are: • Each event has a unique identifier. • A date is associated with an event, indicating when it was created. • An event is associated with a group or department, or a private message. • An event has an author (a user) who has triggered (generated) that event. • Each event has an type. The most common type is Comment, that is a message that an user has published. Other types are related with events such as a new member added, some documents uploaded or deleted, etc.18
  19. 19. REST API entities • The number of child comments that the event has. • Information related with the likes the event has received: number of likes and the last user who did it. • The source of the event gives you information related with the origin of the event. This information is useful for developing integrations; for example we use it to indicate that the event was generated from a device like an Android, iPhone…; or another application Chatter, Yammer… • The text related with the event, use the attribute comment (plain text) and htmlComment (contains html format text). • An extra attribute called payload can be used to store information related with the Event in JSON format.19
  20. 20. REST API entities A Group is the more general structure in Zyncro, it is a workspace where users share information and communicate. Some of the most important attributes related with a Group are: • Each group has a unique identifier. • The name and description of the group. • The owner of the group. • The number of members the group has. • Whether the group is public or private • An extra attribute called payload can be used to store information related with the Group in JSON format.20
  21. 21. REST API entities A Department is similar to a group, but it is only visible to all the organization users. All comments that are published in a department are published in name of the department. Some of the most important attributes related with a Department are: • Each department has a unique identifier. • The name, description, aboutus (and other properties) of the department. • The owner of the department. • An extra attribute called payload can be used to store information related with the Group in JSON format.21
  22. 22. REST API entities A User represents a person registered and using Zyncro. Every user belongs to an organization. Some of the most important attributes related with a User are: • Each user has a unique identifier. • The name, lastname, email (and other properties) of the user. • The current language the user has active. • The identifiers of his Company feed, Personal feed and Personal group. • The identifier of his Organization22
  23. 23. REST API entities • Some of the permissions in the organization: enable publish in Company feed, enable to create Groups or Departments If retrieving the full profile of user, extra information is included such as • Skills, experience and education information • Contact details: address, telephone numbers, mobile • An extra attribute called payload can be used to store information related with the Group in JSON format.23
  24. 24. REST API entities A Member is a user that belongs to a Group or Department with its associated permissions. Some of the most important attributes related with a Member are: • The information included in the User • The permission of the User in the Group/Department: • If can publish new messages • If can comment existing messaged • If is owner of the Group/Department • If can add/edit/delete documents • If can invite other users to join • If can add/edit/delete tasks • If can create Zlinks (public links)24
  25. 25. REST API entities Organization, every user in Zyncro belongs to one (and only one) organization, that defines the behavior they have in it. Some of the most important attributes related with an Organization are: • Each organization has a unique identifier. • The name, total users and total storage of the organization • Basic GUI attributes: header color, header text color, image • Configuration attributes such as, if tasks are enable, if message can be deleted, if users can comment on company feed…25
  26. 26. REST API entities A Document belongs to a Group or Department. Some of the most important attributes related with a Document are: • Each document has a unique identifier. • The name and description of the document • Each event has an type, we have four types of documents: • File • Folder • External link (to an URL) • Internal link (to another file in other Group/Department)26
  27. 27. REST API entities • The date and time of creation and last modification • The last document version associated with this document • The number of versions this document has • The member who created the document • The member who last modified the document27
  28. 28. REST API entities A DocumentVersion represents a version of a document. Some of the most important attributes related with a DocumentVersion are: • Each document version has a unique identifier. • The version number, size and date time of creation • The identifier of the group and the document • The information regarding the member author of this version28
  29. 29. REST API entities A InboxEvent is a notification that a user received, generated by an event. Some of the most important attributes related with an Inbox Event are: • Each inbox event has a unique identifier. • The date and time the inbox event was generated • The event associated with the inbox event • Each inbox event has an type, these types are: • Comment • Like • Follow29
  30. 30. REST API entities Invitation Some of the most important attributes related with an Invitation are: • Each invitation has a unique identifier. • The date time when the invitation was sent • Information about the user who sent and the user whose received the invitation • The state of the invitation (waiting, cancelled, accepted, rejected) • Each invitation has an type, these types are: • External contact • Group • Follow30
  31. 31. REST API entities Task Some of the most important attributes related with a Task are: • Each task has a unique identifier. • The name and description of the task • The group identifier where the tasks belongs • The status of the task (pending or completed) • The due date of the task • The user assigned to this task31
  32. 32. Code samples – REST API Some samples using the REST API in several programming languages can be found at github.com/zyncro C# (github.com/zyncro/csharp-api-sample) Java (github.com/zyncro/java-api-sample) PHP (github.com/zyncro/php-api-sample) Python (github.com/zyncro/python-api-sample) More to come…32
  33. 33. PHP API client We provide a series of PHP classes that you can use to invoke REST API services from PHP. OAuth authorization is transparent and you do not have to worry about it, just choose which type to use. https://github.com/zyncro/php-api-client33
  34. 34. PHP API client - Samples • Web browser authorization $dsf->start(new WallApiService($dsf)); $dsf->controller->zyncroApi->logintype = threelegged; $response = $dsf->controller->getEvents(); • External service authorization $dsf->start(new WallApiService($dsf)); $dsf->controller->zyncroApi->email = $email; $dsf->controller->zyncroApi->pass = $pass; $dsf->controller->zyncroApi->logintype = userpass; $response = $dsf->controller->getEvents();34
  35. 35. PHP API client - Samples • Creating a new Group with the API $dsf->start(new GroupApiService($dsf)); $response = $dsf->controller->createGroup (A new Group from PHP API, The description);35
  36. 36. PHP API client - Samples • Publishing a new Message in a Group with the API $dsf->start(new WallApiService($dsf)); $response = $dsf->controller->publishInGroup( syncrum:sharegroup:01e39c19-313e-404c-9d08-64a047eda89c, Hello plain World!, <p>Hello <span style="font-weight:bold; color:#ff0000;">enriched</span> World</p>); • Get Events from a Group with the API $dsf->start(new WallApiService($dsf)); $response = $dsf->controller->getGroupEvents( syncrum:sharegroup:01e39c19-313e-404c-9d08-64a047eda89c);36
  37. 37. More info Zyncro Developers Portal http://developers.zyncro.com37
  38. 38. WWW.ZYNCRO.COM Twitter: @zyncro blog: en.blog.zyncro.com38