Skip to content

API

Jump to bottom Edit New page
James Wilson edited this page Jul 18, 2015 · 6 revisions

API is called on api.php. This is located at https://api.synccit.com/api.php. If not using synccit.com, this should be shown on devices page.

Basic idea. When someone clicks on a link on reddit, the ID of link clicked is sent here. When someone clicks on a comment thread, the number of comments that thead has and it's ID is sent here. So when looking at reddit later, no matter what device, the link will show up read and if there are any new comments.

The API includes 2 variables. The API version and revision. The version is only changed when major changes to the API occur and will break older uses of it. The revision is for smaller changes. This usually means adding features or small changes that don't break any older use of the API.

To determine the version and revision of the API being used, check the headers sent by api.php. curl -I https://api.synccit.com/api.php gives me X-API: 1 and X-Revision: 8. To see how revisions change, you can check the api.php history.

Auth code and passwords

For added security, instead of using the account password for each call, it uses an auth code. These can be created and deleted from the devices page on synccit.com. Auth codes are currently 6 character randomly generated strings.

For ease of use on the user's side, accounts can be created and auth codes added via the API. This can allow someone without an account to be up and running with synccit within a few seconds.

Implementations

Variables

  • username
  • synccit username
  • auth
  • device auth code (users get this from devices page)
  • As of revision 11, password will be accepted (though auth code should still be used instead)
  • dev
  • Your developer name
  • Name you want to appear as, such as synccit-userscript or iReddit
  • devauth
  • developer authentication
  • Note: Not implemented yet. This will allow you to ensure only you can use your developer name
  • mode
  • Action you're taking.
  • read - get read links/comments
  • history - get read links/comments since time (only for JSON/XML)
  • update - update links/comments
  • create - create new account (only for JSON/XML)
  • addauth - add new authorization code (only for JSON/XML)
  • api
  • API version you're using (not required)
  • Current version is 1
  • links
  • Array of links (JSON/XML)
  • Comma separated list of link ids (Plain Text)
  • comments
  • Only for plain text mode
  • Comma separated list of link ids with comment count
  • Link id and comment count separated by :
  • time
  • Only for history call
  • Unix timestamp to get links since that time
  • Optional. Defaults to 0
  • offset
  • Only for history call
  • History returns at most 100 links per call
  • To get further, set offset a multiple of 100
  • Ex. links 101-200, offset needs to be 100
  • Optional. Defaults to 0

Link update variables (JSON/XML)

  • id
  • Reddit link id. 6 character (usually) unique id for each reddit link
  • Ex: http://www.reddit.com/r/Android/comments/16bond/amazon_introduces_autorip_a_new_service_that/
  • id would be 16bond
  • comments
  • Number of reddit comments
  • If not present, only link will update
  • both
  • true/false
  • Only matters when comments set
  • If true, link will be marked as visited and comment count updated (for self posts)
  • If false (assumed), only comment count will be updated
  • time
  • Not implemented yet
  • Custom time to mark link as read

Link (returned) read variables (JSON/XML)

  • id
  • Reddit link id (see above)
  • lastvisit
  • Unix time stamp of when link was last visited
  • Defaults to 0 if link has never been visited
  • comments
  • Number of comments read
  • Defaults to 0 if comments have never been viewed
  • commentvisit
  • Unix time stamp of when comments were last viewed
  • Defaults to 0 if comments have never been viewed

Create account / add authorization variables (JSON/XML)

  • password
  • Password for account
  • email
  • Email to be associated with account (create account only)
  • Not required
  • device
  • Device name for the authorization code (add auth only)
  • auth
  • The created auth code (add auth return)

JSON

JSON data is sent of POST variable data

The GET or POST variable type should be json (though not required)

Example JSON update call

{
    "username" 	: "james",
	"auth"		: "9m89x0",
	"dev"		: "synccit json",
	"mode"		: "update",
	"links"		: [
		{
			"id" : "111111"
		},
		{
			"id" : "222222",
			"comments" : "132"
		},
		{
			"id" : "333333",
			"comments" : "313",
			"both" : true
		},
		{
			"id" : "444444"
		}
	]
}

synccit username is james. Auth code is 9m89x0. The developer is synccit json. Mode is update

This will update 4 links.

  • 111111 - Link marked as read at current time
  • 222222 - 132 comments marked as read. Link still unread
  • 333333 - Link marked as read at current time. 313 comments marked as read
  • 444444 - Link marked as read at current time

Returns

Success

{
	"success"	: "4 links updated"
}

Error

{
	"error"	: "ERROR_CODE"
}

Example JSON read call

{
	"username" 	: "james",
	"auth"		: "9m89x0",
	"dev"		: "synccit json",
	"mode"		: "read",
	"links"		: [
		{
			"id" : "111111"
		},
		{
			"id" : "222222"
		},
		{
			"id" : "333333"
		},
		{
			"id" : "555555"
		}
	]
}

Nearly same as update call. Mode is now read instead of update

4 links are checked. Only need id

Returns

[
    {
        "id"            : "111111",
        "lastvisit"     : "1357891889",
        "comments"      : "0",
        "commentvisit"  : "0"
    },
    {
        "id"            : "222222",
        "lastvisit"     : "0",
        "comments"      : "132",
        "commentvisit"  : "1357891889"
    },
    {
        "id"            : "333333",
        "lastvisit"     : "1357891889",
        "comments"      : "313",
        "commentvisit"  : "1357891889"
    }
]

3 links are returned.

  • 111111 - Link visited at 1357891889. Comments never viewed
  • 222222 - 132 comments read. Link never visited
  • 333333 - Link visited at 1357891889. 313 comments read

Link 555555 not returned since it was never updated.

Example JSON history call

{
    "username"  : "james",
    "auth"      : "9m89x0",
    "dev"       : "synccit json",
    "mode"      : "history",
    "offset"    : "0",
    "time"      : "1357891889"

}

Nearly same as read call. Mode is now history instead of read

Gets the links visited since time. Will return at most 100 links. To get links 101-200, make offset 100. For 201-300, offset = 200, etc.

time and offset are optional, and will default to 0.

Returns

[
    {
        "id"            : "111111",
        "lastvisit"     : "1357891889",
        "comments"      : "0",
        "commentvisit"  : "0"
    },
    {
        "id"            : "222222",
        "lastvisit"     : "0",
        "comments"      : "132",
        "commentvisit"  : "1357891889"
    },
    {
        "id"            : "333333",
        "lastvisit"     : "1357891889",
        "comments"      : "313",
        "commentvisit"  : "1357891889"
    },
    {
        "id"            : "444444",
        "lastvisit"     : "1357891889",
        "comments"      : "0",
        "commentvisit"  : "0"
    }
]

4 links are returned.

  • 111111 - Link visited at 1357891889. Comments never viewed
  • 222222 - 132 comments read. Link never visited
  • 333333 - Link visited at 1357891889. 313 comments read
  • 444444 - Link visited at 1357891889. Comments never viewed

Example JSON create account call

{
    "username"  : "newuser",
    "password"  : "thebestpasswordever",
    "dev"       : "synccit demo",
    "email"     : "[email protected]",
    "mode"      : "create"
}

Creates new user with username newuser and password thebestpasswordever. And an email of [email protected], though email is not required. Mode is create

Returns

Success

{
    "success"   : "account created"
}

Error

{
    "error"     : "ERROR_CODE"
}

Example JSON add authorization call

{
    "username"  : "newuser",
    "password"  : "thebestpasswordever",
    "dev"       : "synccit demo",
    "device"    : "developer API device",
    "mode"      : "addauth"
}

Creates a new auth code for the user newuser with password thebestpasswordever. Device name is developer API device. Mode is addauth

Returns

Success

{
    "success"   : "device key added",
    "device"    : "developer API device",
    "auth"      : "409ssj"
}

New device key added with auth code of 409ssj. Device name is also returned back

Error

{
    "error" : "ERROR_CODE"
}

XML

XML data is sent on POST variable data.

The GET or POST variable type has to be set to xml or, as of API revision 10, the first 4 charaters of POST data are <?xml

Example XML update call

<?xml version="1.0"?>
<synccit>
    <username>james</username>
    <auth>9m89x0</auth>
    <dev>synccit xml</dev>
    <mode>update</mode>

    <links>
        <link>
            <id>111111</id>
        </link>
        <link>
            <id>222222</id>
            <comments>132</comments>
        </link>
        <link>
            <id>333333</id>
            <comments>313</comments>
            <both>true</both>
        </link>
        <link>
            <id>444444</id>
        </link>
 
    </links>
</synccit>

synccit username is james. Auth code is 9m89x0. The developer is synccit xml. Mode is update

This will update 4 links.

  • 111111 - Link marked as read at current time
  • 222222 - 132 comments marked as read. Link still unread
  • 333333 - Link marked as read at current time. 313 comments marked as read
  • 444444 - Link marked as read at current time

Returns

Success

<?xml version="1.0"?>
<synccit>
    <success>4 links updated</success>
</synccit>

Error

 <?xml version="1.0"?>
 <synccit>
	    <error>ERROR_CODE</error>
 </synccit>

Example XML read call

<?xml version="1.0"?>
<synccit>
    <username>james</username>
    <auth>9m89x0</auth>
    <dev>synccit xml</dev>
    <mode>read</mode>

    <links>
        <link>
            <id>11111</id>
        </link>
        <link>
            <id>222222</id>
        </link>
        <link>
            <id>333333</id>
        </link>
        <link>
            <id>555555</id>
        </link>
    </links>
</synccit>

Nearly same as update call. Mode is now read instead of update

4 links are checked. Only need id

Returns

<?xml version="1.0"?>
<synccit>
	<links>
		<link>
			<id>111111</id>
			<lastvisit>1357881500</lastvisit>
			<comments>0</comments>
			<commentvisit>0</commentvisit>
		</link>
		<link>
			<id>222222</id>
			<lastvisit>0</lastvisit>
			<comments>132</comments>
			<commentvisit>1357881500</commentvisit>
		</link>
		<link>
			<id>333333</id>
			<lastvisit>1357881500</lastvisit>
			<comments>313</comments>
			<commentvisit>1357881500</commentvisit>
		</link>
	</links>
</synccit>

3 links are returned.

  • 111111 - Link visited at 1357881500. Comments never viewed
  • 222222 - 132 comments read. Link never visited
  • 333333 - Link visited at 1357891889. 313 comments read

Link 555555 not returned since it was never updated.

Example XML history call

<?xml version="1.0"?>
<synccit>
    <username>james</username>
    <auth>9m89x0</auth>
    <dev>synccit xml</dev>
    <mode>history</mode>
    <offset>0</offset>
    <time>1357881500</time>
</synccit>

Nearly same as read call. Mode is now history instead of read

Gets the links visited since time. Will return at most 100 links. To get links 101-200, make offset 100. For 201-300, offset = 200, etc.

time and offset are optional, and will default to 0.

Returns

<?xml version="1.0"?>
<synccit>
    <links>
        <link>
            <id>111111</id>
            <lastvisit>1357881500</lastvisit>
            <comments>0</comments>
            <commentvisit>0</commentvisit>
        </link>
        <link>
            <id>222222</id>
            <lastvisit>0</lastvisit>
            <comments>132</comments>
            <commentvisit>1357881500</commentvisit>
        </link>
        <link>
            <id>333333</id>
            <lastvisit>1357881500</lastvisit>
            <comments>313</comments>
            <commentvisit>1357881500</commentvisit>
        </link>
        <link>
            <id>444444</id>
            <lastvisit>1357881500</lastvisit>
            <comments>0</comments>
            <commentvisit>0</commentvisit>
        </link>
    </links>
</synccit>

4 links are returned.

  • 111111 - Link visited at 1357881500. Comments never viewed
  • 222222 - 132 comments read. Link never visited
  • 333333 - Link visited at 1357891889. 313 comments read
  • 444444 - Link visited at 1357881500. Comments never viewed

Example XML create account call

<?xml version="1.0"?>
<synccit>
    <username>newuser</username>
    <password>thebestpasswordever</password>
    <dev>synccit demo</dev>
    <email>[email protected]</email>
    <mode>create</mode>
</synccit>

Creates the user newuser with a password of thebestpasswordever. And an email of [email protected], though email is not required. Mode is create

Returns

Success

<?xml version="1.0"?>
<synccit>
    <success>account created</success>
</synccit>

Error

<?xml version="1.0"?>
<synccit>
    <error>ERROR_CODE</error>
</synccit>

Example XML add authorization

<?xml version="1.0"?>
<synccit>
    <username>newuser</username>
    <password>thebestpasswordever</password>
    <dev>synccit demo</dev>
    <device>developer API device</device>
    <mode>addauth</mode>
</synccit>

Creates a new auth code for the user newuser with password thebestpasswordever. Device name is developer API device. Mode is addauth

Returns

Success

<?xml version="1.0"?>
<synccit>
    <success>device key added</success>
    <device>developer API device</device>
    <auth>303b09</auth>
</synccit>

Returns auth code under auth. Use this for future API calls for this user.

Error

<?xml version="1.0"?>
<synccit>
    <error>ERROR_CODE</error>
</synccit>

Plain Text

Data just sent as POST variables

Example update call

username=james&auth=9m89x0&dev=stext&mode=update&links=111111,333333,444444&comments=222222:132,333333:313

synccit username is james. Auth code is 9m89x0. The developer is stext. Mode is update

This will update 4 links.

  • 111111 - Link marked as read at current time
  • 222222 - 132 comments marked as read. Link still unread
  • 333333 - Link marked as read at current time. 313 comments marked as read
  • 444444 - Link marked as read at current time

Returns

Success

success: 4 links updated

Error

error: ERROR_CODE

Example read call

username=james&auth=9m89x0&dev=stext&mode=read&links=111111,222222,333333,555555

Nearly same as update call. Mode is now read instead of update

4 links are checked. Only need links variable. Comments are automatically checked

Returns

111111:1356731259;0:0,
222222:0;132:1356731259,
333333:1356731259;313:1356731259,

Format is:

link_id:link_visited_time;comment_count:comment_visited_time,

3 links are returned.

  • 111111 - Link visited at 1356731259. Comments never viewed
  • 222222 - 132 comments read. Link never visited
  • 333333 - Link visited at 1356731259. 313 comments read

Link 555555 not returned since it was never updated.

Error Codes

  • no post data
  • No post data sent or at least none that we know what to do with
  • not authorized
  • Username and auth code combination doesn't work
  • no links requested
  • No links submitted to be checked
  • no links found
  • None of links requested have history (only in plain text mode)
  • database error
  • Error executing query. Likely something on our end
  • username or password wrong
  • That username and password combination isn't valid

Create account errors

  • email not valid
  • Not valid email given. Only checks it '@' exists
  • username needs to be at least 3 characters long
  • password needs to be at least 6 characters long
  • username must consist of letters, numbers, or underscores
  • username already exists
  • Username is taken. Try something else

License

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

PBKDF2 file from https://defuse.ca/php-pbkdf2.htm Released under public domain

Blue icons from http://mebaze.com/freebies/bunch-of-cool-bluish-icons

1140 css grid from http://cssgrid.net/

laptop/iphone icon http://brsev.deviantart.com/

Traditional certificates are rapidly giving way to their digital counterparts - - in the ever-changing environment of education and professional development. These digital badges are changing the way we acknowledge and display our accomplishments in various learning paths.

Digital Badges vs. Digital Certificates

Before we get into the world of digital badges, it's important to understand the distinction between digital certificates and badges. Certificates digital:

Digital Certificates are electronic counterparts to paper certificates. They have the same weight and relevance but provide additional benefits. Digital certificates can be used to demonstrate the completion of a course, a degree, or a specialized ability. They are frequently accepted as credible proof of achievement by educational institutions and employers. Digital Awards: Digital Badges, on the other hand, have greater flexibility. They are frequently used to honor individual accomplishments or skills within the context of a larger learning journey. Consider them modest marks of achievement that can be gained along the journey. These badges can symbolize abilities like problem-solving, critical thinking, or mastery of a certain software product. In the field of online learning, they are analogous to merit badges. The Effectiveness of Digital Badges in Learning Pathways

Digital badges have grown in popularity in recent years, and with good reason:

Unlike traditional certificates, which frequently indicate a broad course completion, digital badges provide granular recognition. Learners can demonstrate specific abilities acquired throughout a course or program.

Digital Badges for students can be used to motivate people. They provide rapid feedback for a learner's efforts, motivating them to continue along a learning path.

Employability: As the job market gets more competitive, digital badges can be used to demonstrate practical abilities. Employers can easily find applicants who have the abilities they require.

Ease of Verification: Traditional certificate verification can be time-consuming. Verification is as simple as a click away with digital badges. A badge's legitimacy can be easily verified by employers or educational institutions.

Using Digital Badges in Education

Here are some critical steps for educators and institutions exploring the use of digital badges:

Identify abilities: Determine which specific abilities or achievements within a learning pathway merit badge recognition.Create visually stunning badges that properly represent the acknowledged abilities or accomplishments.

Badge Issuance: Establish criteria for badge earning. Make it possible for students to receive badges based on their performance or completion of specified activities.

Digital Badge Platforms: Make use of digital badge platforms or software to create, issue, and manage badges. Integrate badges into your learning management system or online courses so that learners may easily view and share their badges.

Truscholar: A Powerful Partnership While digital certificates are still important for recognizing course and degree completion, digital badges provide richness and granularity to the learning experience. They work together to develop a comprehensive recognition system that benefits learners, educators, and businesses alike.

Add a custom sidebar
Clone this wiki locally