Overview

A number of the services provided by the ONEsite REST API are publicly consumable; meaning that a visitor to one of your sites will be able to view the results of a REST API call when the Web Page loads. For example, if you have embedded the results of a call to the Photo Service into the Web page, the visitor to the page will have immediate access to view the photographic results of the service call. Public services generally extend to “read only” services and thus can only retrieve data marked as ‘public’ in the ONEsite content permissions system.

Other services, such as those which might allow the updating of data, require several steps in order to successfully complete the call to the service. First, verification of the legitimacy of the service user must be performed. This prevents anonymous attempts to update data and allows ONEsite to verify that a user is not attempting to access data they are not authorized to access. Second, after the session has been verified a “developer key” must be passed with the call to the ONEsite REST API. This allows our servers to identify the client making the call and verify access to the service and data being requested. These two steps allow us to track users that are accessing services and to limit the resources they are able to consume through the ONEsite API.

The devkey will be provided to you by your ONEsite Project Manager. Additionally, your ONEsite Developer Lead will provide you with all of the necessary documentation and will guide you through the process of setting up, testing, and deploying your use of the ONEsite REST API Services.

Devkey Security Overview

ONEsite REST Web Services uses a “devkey”, short for “developer key”, to guide access to services. The devkey is an alphanumeric code that is provided to clients accessing the services. This devkey is used to verify the services and actions that may be performed. Multiple devkeys may be issued if you need to have some services available in the client browser and other services available in a more secure fashion.

When the client calls the REST Web Services, the following parameters (at a minimum) should be passed:

Name Description
devkey The key that is used to uniquely identify the client accessing the services.
service The name of the actual service being utilized
action The method that is being performed. This will be a method exposed by the service API.

Example

https://example.svcs.onesite.com/rest/ugcVideo?action=delete&devkey=123abc&contentID=164672

In this example the service being called is “ugcVideo”. The action being called is “delete”. The devkey being passed is “123abc”. When the service is activated, the first thing that the service will do is verify that devkey “123abc” has rights to execute the “delete” action on the “ugcVideo” service.Using a devkey (in conjunction with IP tracking and SSL) enables ONEsite to control access to the ONEsite REST Web Services. The devkey is also used to log access to web services. ONEsite is able to track all access to ONEsite REST Web Services using the devkey that is provided to the client.

User Level Authentication

The ONEsite services also support direct access by users. The user may authenticate in one of several manners and hit the services to create or manipulate their own content.

Web Session Authentication

The user passes their session identifier and session security identifier to the web service.coreU – their session identifiercoreX – their session security identifierSession authentication is then performed against these session credentials. A new user session may be created by hitting the svcLogin web services.

Basic Authentication

The user enters in their username and password in response to an HTTP Authentication prompt by the secure services server. Passing ‘userAuth’ as a GET parameter will trigger this authentication mechanism.

Request

GET /rest/svcStatus?action=updateStatus&userAuth&status=new%20status&mood=happy HTTP/1.1
Host: services.onesite.com

Response

HTTP/1.x 401 Unauthorized
WWW-Authenticate: Basic realm="ONEsite Services"

Subsequent Request

GET /rest/svcStatus?action=updateStatus&userAuth&status=new%20status&mood=happy HTTP/1.1
Host: services.onesite.com
Authorization: Basic YW5kcmV3OnBhc3N3b3JkMQ==

Subsequent Response

HTTP/1.x 200 OK

Supported Services

Service actions that currently have support for User Level Authentication:

  • svcFriendship
    • getFriends
    • makeFriend
  • svcGeoPoints
    • getGeoData
    • setLatLon
  • svcStatus
    • getStatus
    • updateStatus
  • ugcMessage
    • userNotificationSummary
  • ugcPhoto
    • uploadPhoto
    • setProfilePhoto
  • svcUsers
    • getUserDetail