Status Messages

Guides, Help & Support, Tutorials and Examples on how to access and use the Site API.
4 posts Page 1 of 1
Contributors
User avatar
CodenStuff
Site Admin
Site Admin
Posts: 4389
Joined: Tue Aug 04, 2009 1:47 am

Status Messages
CodenStuff
The Codenstuff Site API (WIP)

Status Messages

At the moment the API allows you to access the following data on the site:

Status Messages & Message replies
Your own profile information
Grab a list of all your friends
Get your friends profile information
Post/Delete Messages & replies


So everything required to access and use the Status Messages feature on the site is available now in the API.

The API can be accessed via the following URL:
api/LiveAPIJsonXML.php
These are the URL variables required to access the relevant information:

output
  • json (Get data in Json format - Default)
  • xml (Get data in XML format)
mode
  • Messages (Get a list of all recent status messages - Default)
  • UserMessages (Get a specific members status messages)
  • SelfProfile (Get your profile information)
  • UserProfile (Get another users profile information)
  • Mates (Get a list of all your friends)
  • DelM (Delete a message)
  • DelMR (Delete a message reply)
  • NewM (Post a new message)
  • NewMR (Post a new message reply)
username (This would be your site username)
twid (This would be the member ID number of another user/friend)
skey (This is your personal secret API key)
newm (The text for posting a new message/reply/post)
messid (The id number of a message when editing/posting replies ect)

You can use these variables in either GET or POST requests. The variables marked with 'Default' indicates the default value of that variable. Modes highlighted in orange are GET only requests and those highlighted in blue are POST only.

OK so how would we use those?. Lets see a few examples...

Get a list of all messages:
Code: Select all
/LiveAPIJsonXML.php?mode=Messages&username=USERNAME&skey=ABCD123456
Get a list of all recent/new messages:
Code: Select all
/LiveAPIJsonXML.php?mode=Messages&username=USERNAME&skey=ABCD123456&messid=234
Now "messid" would tell the API that you want new messages only and not all the messages. Each message you get from the API has an 'id' number and you use this number for example when posting a reply to a message so the API knows which message you are replying too.

An example of how to get new messages would be lets say we first got a list of ALL messages what we would do is save the highest message 'id' from that list so lets say the highest message id is 234. Now we already have all the messages so we dont want to get the full list again just to display new ones so we would just ask the API to send us messages with an 'id' higher than 234 so only new messages posted since we last got the list would be sent to us.

You will notice I included 'username' and 'skey' variables in that URL and that is because you are required to send that information with every API call in order to verify who you are and that you have permission to use it. I also didn't give it an 'output' variable because the API automatically sends data in Json format but if I wanted it in XML I would change my call URL to:
Code: Select all
/LiveAPIJsonXML.php?mode=Messages&username=USERNAME&skey=ABCD123456&output=xml
Get a list of friends:
Code: Select all
/LiveAPIJsonXML.php?mode=Mates&username=USERNAME&skey=ABCD123456
Get your profile information:
Code: Select all
/LiveAPIJsonXML.php?mode=SelfProfile&username=USERNAME&skey=ABCD123456
Get a friends profile information:
Code: Select all
/LiveAPIJsonXML.php?mode=UserProfile&twid=23&username=USERNAME&skey=ABCD123456
In this one we added the 'twid' variable because we need to tell the API which friends data we want.

Ok so I think that covers the basics on usage of the API and how to access the various pieces of data so I will move on and try to explain how the data received is formatted.

To learn how to post and delete messages please see this post: viewtopic.php?f=226&t=10259&p=74534#p74534

See post below!.
Welcome to CodenStuff.com Learn Code, Love Code. Thank you for being a member of the community.
User avatar
CodenStuff
Site Admin
Site Admin
Posts: 4389
Joined: Tue Aug 04, 2009 1:47 am

Re: Status Messages
CodenStuff
Status Messages

In this post we will go through how the data received from the API is laid out. It doesnt matter if you use Json or xml the data is laid out in the same way.

Each part of the data has an item name and item value.

Messages & UserMessages
  • id = The message ID
  • dt = Date&Time of the message
  • message = Message text
  • user_id = Message posted user ID
  • username = Message poster username
  • usercolor = Message poster username color
  • avatar = Message posters avatar
reps = A list of the message replies which has its own items
  • id = Reply ID
  • dt = Reply date & time
  • message = Reply text
  • name = Username of the person who wrote the reply
To get a better idea of what I'm going on about this is what a message looks like in Json:
Code: Select all
{
		"id": "63",
		"dt": "2012-12-25 11:22:43",
		"message": "Merry Christmas everyone!",
		"user_id": "1965",
		"username": "Filip",
		"usercolor": "BFFF00",
		"avatar": ".\/download\/file.php?avatar=1965_1348311067.png",
		"reps": [
			{
				"id": "33",
				"dt": 1356482362,
				"message": "Merry Christmas Filip",
				"name": "comathi"
			},
			{
				"id": "32",
				"dt": 1356482360,
				"message": "Merry Christmas Filip",
				"name": "comathi"
			}
		]
	}


Mates
  • id = Friends user ID
  • name = Friends username
  • avatar = Friends avatar
SelfProfile & UserProfile
  • userid = Users ID
  • userip = Users IP (SelfProfile only)
  • regdate = Date & time user registered on the site
  • username = Users username
  • email = Users email (SelfProfile only)
  • birthday = Users Birthday
  • lastvisit = Date & time of users last site visit
  • lastpost = Date & time of users last post
  • lastpage = The last page the user was on
  • warnings = Number of warnings the user has (SelfProfile only)
  • posts = Number of posts the user has
  • newpm = Number of new private messages user has (SelfProfile only)
  • unreadpm = Number of unread private messages use has (SelfProfile only)
  • avatar = Users avatar URL
  • from = Where user is from
  • icq = Users ICQ
  • aim = Users aim messenger
  • yahoo = Users yahoo messenger
  • msn = Users msn messenger
  • website = Users website URL
  • occupation = Users occupation
  • interests = Users interests
  • reputation = Users reputation level
  • color = Users username color
  • credits = Users credit count (SelfProfile Only)
Hopefully you understand what all that means but if you dont then dont worry in the post below I will show you a code example on how to use this information in a .net project.

See the post below for a code example cooll;
Welcome to CodenStuff.com Learn Code, Love Code. Thank you for being a member of the community.
User avatar
CodenStuff
Site Admin
Site Admin
Posts: 4389
Joined: Tue Aug 04, 2009 1:47 am

Re: Status Messages
CodenStuff
Status Messages

An example in VB.net showing how to get and display the data retrieved from the API.

Some libraries are available to help consume Json data like Json.net that can be found here: http://json.codeplex.com/

For this example we are using the System.Web.Extensions.dll assembly which you will need to add a reference too in your project.

First thing we need to do is create an object class to hold our json data when deserialized so its easy to access and use and the classes we create need to have the same item identifiers as the json data from the API. If you remember the post above where we went through the json item data which looked like:
  • id
  • dt
  • message
  • userid
...and so on these are the same identifiers that we need to add into our class. Lets see how we would do this to get and
store message data from the API.

Our class would look like this:
Code: Select all
    Public Class Message
        Public id As String
        Public dt As String
        Public message As String
        Public userid As String
        Public username As String
        Public usercolor As String
        Public avatar As String
        Public reps As List(Of Replies)
    End Class
Once again as you can see using the same item names as our json data. Each message can also contain replies identified by 'reps' so we create another smaller class to hold our replies for each message. We build a list of class 'Message' for each message in json and we build a list of 'Replies' for each message within our 'Message' class so that each individual message has its own replies within it:
Code: Select all
    Public Class Replies
        Public id As String
        Public dt As String
        Public message As String
        Public name As String
    End Class
Yep I'm a little confused myself but you will get the idea lol. OK how on earth do we get the json into there? well heres some code that does just that:
Code: Select all
Public Sub GetAllMessages()
        Dim list As List(Of Message)
        Try
            Dim WebClient As New System.Net.WebClient
            Dim Result As String = WebClient.DownloadString("http://www.codenstuff.com/forum/DummyAPIJsonXML.php?username=USERNAME&skey=ABCD123456")
            list = New JavaScriptSerializer().Deserialize(Result, GetType(List(Of Message)))
            For Each item As Message In list
              'Do something with each item
		'item.message
		'item.username
		'item.id
            Next
        Catch ex As Exception
        End Try
    End Sub
And thats it!. You can now read json, well done you :)

OK ill explain what is happening in that code. First we create a list using our Message class:
Code: Select all
Dim list As List(Of Message)
Then we use a webclient to grab the json data from the API:
Code: Select all
Dim Result As String = WebClient.DownloadString("http://www.codenstuff.com/forum/DummyAPIJsonXML.php?username=USERNAME&skey=ABCD123456")
I add my user ID and API key in the URL because it is required.

Now that we have our data we deserialize it using a JavaScriptsSerializer into individual messages which are then put into our list....Nice!.
Code: Select all
list = New JavaScriptSerializer().Deserialize(Result, GetType(List(Of Message)))
Notice we are deserializing it into a list of Message using:
Code: Select all
GetType(List(Of Message))
We would change this depending on the class we wanted to use, for example to get a list of friends we may have a 'Friends' class so the code would be:
Code: Select all
list = New JavaScriptSerializer().Deserialize(Result, GetType(List(Of Friends)))
So we have our list of messages and we want to display them and we can use a for each loop to do that:
Code: Select all
For Each item As Message In list
              'Do something with each item
		'item.message
		'item.username
		'item.id
            Next
For each message in our list we want to do something like display each one in a custom control or a listbox or whatever. You can access each property of a message by simply using 'item.something', for example lets say we wanted to display the username from each message into a listbox we would do:
Code: Select all
For Each item As Message In list
              Listbox.Items.add(item.username)
            Next
It would take a while to go through all the ways you could use this data but at the end of the day that is entirely up to you.
And that ends out quick tutorial and now you know how to display a list of status messages from the API, simple rite?.

We would follow the same process when requesting other data from the API for example getting a list of friends out class would be:
Code: Select all
    Public Class Friends
        Public id As String
        Public name As String
        Public avatar As String
    End Class
And the json code to get that would be:
Code: Select all
Public Sub GetFriends()
        Dim list As List(Of Friends)
        Try
            Dim WebClient As New System.Net.WebClient
            Dim Result As String = WebClient.DownloadString("http://www.codenstuff.com/forum/DummyAPIJsonXML.php?mode=Mates&username=USERNAME&skey=ABCD123456")
            list = New JavaScriptSerializer().Deserialize(Result, GetType(List(Of Friends)))
            For Each item As Friends In list
              'Do something with each item
		'item.id
		'item.name
		'item.avatar
            Next
        Catch ex As Exception
        End Try
    End Sub
This has been a quick code example on one way of accessing and using json data in VB.net and obviously you can use your own coding style and create your own functions etc to make it easier and a lot better to work with but if your new to json then this is a good start.

Below is a badly coded example project showing how to access to various data from the API and display it.
ApiMessagesExample.zip
I hope you found this helpful and I will update it in the future when we add more stuff.

Happy coding cooll;
You do not have the required permissions to view the files attached to this post.
Welcome to CodenStuff.com Learn Code, Love Code. Thank you for being a member of the community.
User avatar
CodenStuff
Site Admin
Site Admin
Posts: 4389
Joined: Tue Aug 04, 2009 1:47 am

Re: Status Messages
CodenStuff
Posting & Deleting

In this post we will go over how to use the API for posting and deleting both messages and replies.

Most featured of the API are available using GET requests but when submitting new messages/replies you must do this using POST method otherwise it will not go through and the message text itself must be Json encoded using the property name 'message'.

An example of creating and encoding a message to Json in VB.net:

We have a new message class:
Code: Select all
    Public Class NewMessage
        Public message As String
    End Class
Then a function to encode the message to Json:
Code: Select all
    Public Function ToJson(obj As Object) As String
        Dim serializer As New JavaScriptSerializer()
        Return serializer.Serialize(obj)
    End Function
Now we create the message:
Code: Select all
Dim NM As New NewMessage
NM.message = "This is a message"
Finally when posting it to the API we encode it first:
Code: Select all
ToJson(NM)
How to post a new message
To post a new message you need to include the following variables in your post request.

mode=NewM
username=USERNAME
skey=SECRET_KEY
newm=ENCODED_JSON_MESSAGE


After posting a new message you will recieve a message id number from API and you can use this to dynamically add the new message to your display or whatever you are doing depending on the type of app/software your making lol.

How to post a reply
As with the new message code your reply must also be encoded to Json using the property name 'message'.
To post a reply to a message you will need to include the following variables in your post request.

mode=NewMR
username=USERNAME
skey=SECRET_KEY
messid=ID_OF_THE_MESSAGE_YOUR_REPLYING_TOO
newm=ENCODED_JSON_REPLY_MESSAGE


'messid' must be sent when posting a reply so that the API knows which message you are replying too. After posting a reply you recieve a reply 'id' number and again you can use this to dynamically add the reply to your message display or whatever you need to do with it.

For deleting items you can use either GET or POST requests.

How to delete a message
To delete a message you will need to include the following variables in your post request.

mode=DelM
username=USERNAME
skey=SECRET_KEY
messid=ID_OF_MESSAGE_YOU_WANT_TO_DELETE


Example using GET: /API.php?mode=DelM&username=USERNAME&skey=SECRETKEY&messid=123

You can only delete your own messages.

How to delete a reply:
To delete a reply you will need to include the following variables in your post request.

mode=DelMR
username=USERNAME
skey=SECRET_KEY
messid=ID_OF_REPLY_YOU_WANT_TO_DELETE


Example using GET: /API.php?mode=DelMR&username=USERNAME&skey=SECRETKEY&messid=123

You can only delete your own replies.


And that is how you submit or delete messages and replies. cooll;
Welcome to CodenStuff.com Learn Code, Love Code. Thank you for being a member of the community.
4 posts Page 1 of 1
Return to “Codenstuff API”