Web Services Login with OAuth2 Object: OAuthResponse Object: S2CRes Object: S2CRequest Object: User Object: Group Object: Channel Object: Snippet Object: Snippet Property Object: Default Property

Web Services

Snip2Code services may be programmatically consumed via a set of RESTful APIs.
Some methods need to be called by an authenticated user. You can authenticate the user by delving into the charming world of OAuth 2, with the OAuth2 authentication method of Snip2Code API v2
After this procedure has been successfully completed, you are eligible to consume every Web Method of Snip2Code interface.
Make sure to add the following headers to all the HTTP requests:
Content-Typeapplication/x-www-form-urlencoded
CharsetUTF-8
Acceptapplication/json or text/xml
Below there is the complete list of APIs that can be programmatically invoked from a client.
Here you can interactively try out all the methods: give a look!
 

Using OAuth to autenticate on behalf of a user

The authentication via OAuth2 needs three steps.

STEP N. 1

In the first one, an HTTP GET request should be sent to the url:
http://www.snip2code.com/OAuth/RequestToken 
The following headers should be added to the request:
Content-Typeapplication/x-www-form-urlencoded
CharsetUTF-8
Acceptapplication/json
The response to this call will be a JSON-formatted OAuthResponse object containing a RequestToken.

STEP N. 2

Then, in the second step an HTTP POST request should be sent to the url:
http://www.snip2code.com/OAuth/AccessToken 
With the following parameters (data should be formatted as 'form-encoded'):
oauth_tokenthe RequestToken retrieved in the first step
usernameemail or nickname of the user
passwordMD5 hash of the password of the user (*)
grant_typethe string unused
(*) Make sure to use Unicode encoding of the password to hash. An example of the correct method to implement such activity is provided with this snippet to compute the MD5 Hash of a string
The following headers should be added to the request:
Content-Typeapplication/x-www-form-urlencoded
CharsetUTF-8
Acceptapplication/json
The response to this call will be a JSON-formatted OAuthResponse object containing an AccessToken. You want to use the AccessToken in all the following HTTP requests to impersonate the identity of the user with the provided credentials. This can simply be done creating and adding to the HTTP requests a Cookie with the following structure:
Nameoauth_token
Valuethe AccessToken retrieved in the second step
Path/
Domainwww.snip2code.com
Expirationfar in the future...

STEP N. 3 (OPTIONAL)

Eventually, as a third (optional) step, you want to retrieve user information like preferences, groups, etc. by making an HTTP GET request to the url:
http://www.snip2code.com/OAuthUser/GetUser 
With the following querystring parameters:
usernameemail or nickname of the user
passwordMD5 hash of the password of the user (*)
(*) Make sure to use Unicode encoding of the password to hash. An example of the correct method to implement such activity is provided with this snippet to compute the MD5 Hash of a string
The following headers should be added to the request:
Content-Typeapplication/x-www-form-urlencoded
CharsetUTF-8
Acceptapplication/json or text/xml
The response to this call will be a User object containing all the information of the specified user.

TOKEN REFRESH

The AccessToken has a period of validity, specified by the 'Expires' field of OAuthResponse object retrieved in the second step. After this period elapses, you may re-do the same authentication procedure from the very beginning or you may refresh your current AccessToken by making an HTTP GET request to the url:
http://www.snip2code.com/OAuth/RefreshToken 
With the following querystring parameters:
refreshTokenthe RefreshToken retrieved in the second step
The following headers should be added to the request:
Content-Typeapplication/x-www-form-urlencoded
CharsetUTF-8
Acceptapplication/json
The response to this call will be a JSON-formatted OAuthResponse object containing an AccessToken that should be used in the very same way as done in the second step.

OAuthResponse

This is the structure used to expose the stuff related to OAuth procedure. This bean is used both for the RequestToken, and for the AccessToken exchange.

Fields

Name Data TypeDescription
RequestToken string the first code received by the user. It should be enchanged with an AccessToken.
AccessToken string the code that should be used to authenticate the user in the following HTTP requests
Expires int number of seconds after which the AccessToken will be no more valid
RefreshToken string the code that should be used to refresh the expiration of an AccessToken
Scope string (future use) environment where the token is valid. Up to now is not used
Error string error message in case something goes wrong with the call for a token
Success bool true if the call for a token has been successful, false otherwise
RequireSsl bool (future use) true if the following communication should be performed over SSL channel, false otherwise. Up to now it is not used

Example (Response to RequestToken)

{
    "RequestToken":"468c259bbb1e45c1b6e70556e372e383",
    "AccessToken":null,
    "Expires":299,
    "RefreshToken":null,
    "Scope":null,
    "Error":null,
    "Success":true,
    "RequireSsl":false
}

Example (Response to AccessToken)

{
    "RequestToken":null,
    "AccessToken":"203c166daa6b45fc9f57d7fa8783ebfe",
    "Expires":300,
    "RefreshToken":"a2c98e86c3634896871746524353968e",
    "Scope":null,
    "Error":null,
    "Success":true,
    "RequireSsl":false
}
          

S2CRes

This is the structure used to expose the response of a call to the server. The client will usually deal with such entity as response to its requests, except from particular cases (e.g. the 'Images/Get' method which returns a binary content)

Fields

Name Data TypeDescription
Data variable this is the actual content of the response. It can be one of these 4 four categories: primitive value (e.g. int, long, bool, etc.); list of primitive values; Snip2Code Object (e.g. Group, Snippet, User, etc.); list of Snip2Code Objects
Status ErrorCode it can be 'OK' if the request has been successful, or an error code otherwise. The possible ErrorCodes are:
FAILGeneric error in the execution of the request
NOT_LOGGED_INUser is not yet logged in
TARGET_GROUP_DELETEDThe request applies to an object owned by a deleted group
WRONG_INPUTThe parameters of the request contain wrong values
NOT_ALLOWEDThe current user is not allowed to perform the action
INVALID_INPUT_FORMATThe request is sent with an invalid format or protocol
COMMUNICATION_ERRORThere has been a communication failure between client and server
TIMEOUTThe response takes too long to reach the client
UNKNOWNUnknown error
ExecTime float number of milliseconds to generate the response
TotNum int total number of objects that satisfy the input parameters, without considering the eventual pagination
Misc dictionary of pairs [string : string] further information provided with the response

Example

{
  "Data": true,
  "Status": "OK",
  "ExecTime": 18.0011,
  "TotNum": 1
}
                

S2CRequest

This is the structure used to provide structured data to some of the methods to the server. Check the documentation of the methods to find where this structure is applicable.

Fields

Name Data TypeDescription
Data variable this is the actual content of the request. It can be one of these 4 four categories: primitive value (e.g. int, long, bool, etc.); list of primitive values; Snip2Code Object (e.g. int, long, bool, etc.); list of primitive values; Snip2Code Object (e.g. Group, Snippet, User, etc.); list of Snip2Code Objects
ID long unique identifier of the object which the content applies to

Example

{
  "Data": [
        "sampleTag1",
        "sampleTag2"
    ],
  "ID": 100
}

User

This is the entity that describes a Snip2Code user account. It contains all the user information, except the credentials.

Fields

Name Data TypeDescription
CommID int unique identifier of the user
CommEMail string email address for the notifications and alerts
CommNickName string username of the user
CommPreferences UserPreferences set of preferences and additional information of the user
CommRole enum role of the user (can be 'Normal' or 'Admin')
CommPersonalGroupID int ID of the Group that owns the private snippets of the user
Name string first name of the user
LastName string last name of the user
PictureID long unique identifier of the image of the user
Points int reputation of the user
DefaultGroupID int unique identifier of the Group that will own the newly created snippets if a different one is not specified

Example

{
"CommID":1001,
"CommEMail":"jeff@snip2code.com",
"CommNickName":"jeff",
"CommPreferences":{
  "Description":"Master of the universe",
  "Location":"",
  "WebSite":"www.snip2code.com",
  "RedirectToWebSite":false,
  "ThumbUploadNum":4,
  "GravatarEmail":""
},
"CommRole":"Admin",
"CommPersonalGroupID":1005,
"Name":"Jeff",
"LastName":"Roise",
"PictureID":1001,
"Points":242,
"DefaultGroupID":1000
}
                

Group

This is the entity that describes a Snip2Code group.

A group is a set of Users that can share Snippets just only among themselves, making such snippets 'protected'. A snippet is always owned by a group. The 'Personal' groups are intended to own the private snippets of the users. Every user has his own personal group.

Fields

Name Data TypeDescription
CommID int unique identifier of the group
CommPreferences GroupPreferences set of preferences and additional information of the group
CommCreatorID int ID of the User that created the group
Name string name of the group
Policy enum type of the group (can be 'Personal' or 'Company')
NumOfSnippets int total number of snippets owned by this group
CommMembersCount int total number of followers of this group

Example

{
"CommID": 1005,
"CommPreferences": {
    "ColorCode": "PaleTurquoise",
    "ColorCodeRGB": "#AFEEEE"
},
"CommCreatorID": 1000,
"Name": "Snip2Code Alumni",
"Policy": "Company",
"NumOfSnippets": 10,
"CommMembersCount": 4
}
                

Channel

This is the entity that describes a Snip2Code channel. A channel is a place where similar (public) snippets are collected and published. All the snippets published on a channel usually share the same topic.

A User can create channels and follow other channels. A weekly update is sent by email containing the newest snippets published on the channels that a user is following. Every user can publish his owned snippets into one or more channels which he is following. A channel has the very same structure of a Group.

Fields

Name Data TypeDescription
CommID int unique identifier of the channel
CommPreferences GroupPreferences set of preferences and additional information of the channel
CommCreatorID int ID of the User that created the channel
Name string name of the channel
Policy enum type of the channel (up to now, it is always 'Channel')
NumOfSnippets int total number of snippets published onto this channel
CommMembersCount int total number of followers of this channel

Example

{
"CommID": 1020,
"CommPreferences": {
    "ColorCode": "LightGreen",
    "ColorCodeRGB": "#90EE90"
},
"CommCreatorID": 1002,
"Name": "Java Quick Tips",
"Policy": "Channel",
"NumOfSnippets": 34,
"CommMembersCount": 45
}
                

Snippet

This is the most important entity of the system. It defines the content and all the features of a snippet, together with Tags, Properties and Comments. The fundamental characteristics of a snippet are the Title, the Description, the Code, the Visibility and the Owner (which is always a Group) Regarding the visibility of a snippet:

  1. if the snippet is private:
    • The snippet is visible only to the User that created it.
    • The snippet is manageable only by the user that created it; the OwnerGroupID is the personal group of the creator; Visibility is set to 0 (Private)
  2. if the snippet is protected:
    • The snippet is visible only to the belongers of the group specified in OwnerGroupID.
    • The snippet is manageable only by the admins of the group specified in OwnerGroupID and to the creator (if he is a member of the group specified in OwnerGroupID); the OwnerGroupID is the group that owns the snippet (at the creation, it is specified by the creator in the TargetGroupID field of the snippet); Visibility is set to 10 (Protected)
  3. if the snippet is public:
    • The snippet is visible to everybody.
    • The snippet is manageable only by the admins of the group specified in OwnerGroupID and to the creator (if he is a member of the group specified in OwnerGroupID); the OwnerGroupID is the group that owns the snippet: its value depends on when the snippet has become public. IF the snippet has been directly created as public, OwnerGroupID=personal group of the creator. IF the snippet has been published after its creation, OwnerGroupID keeps the value it had when it was published. Visibility is set to 100 (Public)

Fields

Name Data TypeDescription
CommID long unique identifier of the snippet
CommCreatorID int unique identifier of the User that created the snippet
CommOwnerGroupID int unique identifier of the group that owns the snippet
CommCreated datetime creation date of the snippet
CommModified datetime last date when the snippet has been modified
CommVisibility enum visibility of the snippet (can be 'Private', 'Protected' or 'Public')
CommAvgRating float average rating of the snippet from other users
CommNumVote int number of votes received by the snippet from other users
CommTags array of strings list of the tags describing the snippet
CommProperties array of SnippetProperty list of the properties describing the snippet
CreatorName string name of the user that created the snippet
OwnerGroupName string name of the group that owns the snippet
CreatorImageNum int unique token associated to the picture of the user that created the snippet; it should be appended in the querystring of the HTTP call to retrieve the image of the creator
Name string title of the snippet
Description string description of the snippet (like a comment over a method, explaining the behavior of the snippet code)
Code string actual code that represents the content of the snippet
Rating int rating value given to the snippet by the creator
LinkToSource string HTTP address of the source of the snippet
ExtAuthor string name of the creator of the snippet, if it comes from an external source
PricePerView float price in USD to read the content of the snippet
TargetGroupID int unique identifier of the group that will own the snippet

Example

{
"CommID": 100,
"CommCreatorID": 1000,
"CommOwnerGroupID": 1000,
"CommCreated": "2013-09-06 17:32:49Z",
"CommModified": "2013-09-06 17:32:49Z",
"CommVisibility": "Private",
"CommAvgRating": -1,
"CommNumVote": 0,
"CommTags": [
    "sample"
],
"CommProperties": [
    {
    "Name": "OS",
    "Value": "Windows",
    "SnippetID": 100,
    "IsVisible": true
    }
],
"CreatorName": "admin",
"OwnerGroupName": "___admin@snip2code.com",
"CreatorImageNum": 4,
"CreatorPoints": 242,
"Name": "Sample Snippet",
"Description": "This is a sample",
"Code": "This is an HTML code snip!",
"Rating": -1,
"LinkToSource": "",
"ExtAuthor": null,
"PricePerView": 0,
"TargetGroupID": 1000
}
        

Snippet Property

This entity describes a single property related to a Snippet. Basically a property is a 'key'-'value' pair that can be associated to a snippet to describe it in terms of meta-data. Such properties can be used in the search engine to enhance the search capabilities and provide a fine-tuning of the search for more effective results.

Fields

Name Data TypeDescription
Name string name of the property
Value string value of the property
SnippetID long unique identifier of the snippet which the property refers to
IsVisible bool whether such property is a system property or a user-defined property

Example

{
"Name": "OS",
"Value": "Windows",
"SnippetID": 100,
"IsVisible": true
}
        

Default Property

This entity describes a single property that is used as template for the creation of Snippet Properties. Each default property deals with a frequent characteristic that describes a lot of snippets. E.g. Operating system, language, architecture, OS versions, etc. Users are encouraged to describe their snippets in terms of default properties so that such snippets can be easily found according to ready-to-use template searches.

Fields

Name Data TypeDescription
Name string name of the default property
Order int order among other properties with the same name (e.g. among windows versions, which is the newest?)
PossibleValues array of strings list of values that this property can assume
DependsOn array of SnippetProperty list of properties which this default peoperty depends on. E.g. the default property 'IEVersion' makes sense only if the snippet has the property 'Browser' set to 'IE'.

Examples

{
"Name": "OS",
"Order": 0,
"PossibleValues": [
    "Windows",
    "Mac OS X",
    "Linux",
    "Android",
    "Unix",
    "Solaris",
    "WinMobile",
    "WinCE",
    "qnx",
    "hpux",
    "aix"
],
"DependsOn": null
}
{
"Name": "IEVersion",
"Order": 0,
"PossibleValues": [],
"DependsOn": [
    {
        "Name": "Browser",
        "Value": "IE",
        "SnippetID": -1,
        "IsVisible": true
    }
]
}