Lampcms REST API preview

My Question on Support site for LampCMS project

Hello!

Just want to let you know the status of the API work. Here is what I wrote so far:

Wrote base class for the API, wrote a new type of class called Output. This represents the content that is ready to be sent out to the client and it specific to the output format. Concrete classes representing the output format like Json or XML or Jsonp extend this class.

Wrote the Response class - it represents the body and headers ready to be sent to the client (usually browser but any API client really)

Added a new section to !config.ini called [API]

It has these params:
; Maximum results an API can return per page
MAX_RESULTS = 100
; Dalily access limit for not logged in users
DAILY_LIMIT_ANON = 150
; Daily access limit for logged in users
DAILY_LIMIT_APP = 3000
; Daily limit for authenticated user
DAILY_LIMIT_USER = 10000

Using these settings you can completely restring the access to API to only your partner sites by settings DAILY_LIMIT_ANON = 0
It will prevent any access by anonymous clients


API already supports these basic features: makes use of Http response headers and specific HTTP status codes. For example 404 when content not fount or 406 when the value of request parameter is invalid or 500 in case of error in API

Support for custom headers to indicate client's daily rate limit:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
The X-RateLimit-Reset is the timestamp of the next time limit is reset which is usually the beginning of the next day since rate limit is per day.

API currently supports 2 output formats: JSON and JSONP
support for XML can easily be added by just writing the custom OutputXML class. No changes to other classes will be necessary.

API has support for versioning. This is how most good APIs work - when new version of API is released the old ones still work, so your client programs are not broken. You can just pass the v (version id) in request and start using the new version of API. Current version is 1

Currently I wrote 2 API controllers: questions and question

This is how you use it:
Example URL for api is: domain/api/api.php?v=1&a=questions&start_id=5&limit=1&sort=i_votes&dir=desc&alt=json

Here is the explanation of params:

v = version of API, optional, defaults to 1, so for now you can omit it as 1 is the only version

a = "action" Currently completed controllers for "questions" and "question" actions

limit = number of results to return per API call. Think of it as a per-page number on the website.
sort = sort results by this param. For "questions" allowed values are i_votes to sort by votes,
i_lm_ts to sort by "last modified timestamp",
_id to sort by question id,
i_ans to sort by number of answers

dir = direction of sorting. Allowed values are asc for ascending or desc for descending (default)

start_id = show questions with id greated than this (but not including this) id.

max_id = show questions with id less than but not including this id

starttime = unix timestamp in GMT. Show questions posted after this time

tags = space separated tags. Request must be urlencoded so space char should be replaced with %20
show only questions with these tags

match = when tags value is set you can use this param to set to "all" or "any" to match questions with any of the tags or to return questions that must contain all of the tags

uid = userID. Return only questions posted by this user.

type = Return only questions of this type. Allowed values are: "unans" to return only questions with no answers,
"answrd" to return questions with answers by not with "Accepted" answer, "accptd" to return only questions that have an "Accepted" answer.

Extra params: comments=yes to also include comments (by default comments not included)
body=yes to also include full body of question. By default only the "intro", a short text-only version of the first 150 chars of question is included

You can mix these params. For example you can easily get only unanswered questions that have certain tags and posted after certain time.


Question controller.

This controller returns data for one question specified by the qid param.
Example : domain/api/api.php?a=question&qid=5&sort=i_votes&limit=4

Here the limit applies to number of Answers included in response.
For Question controller you can also sort by "accepted", for example: sort=accepted&limit=1
will return only 1 answer that is an "Accepted" answer.


For both questions and question controllers the returned data includes number of total results and the pageID.
Default pageid = 1, you can pass the pageID in request in order to get questions that did not fit in the per-page limit and you know that are more results. In such cases you use the pagination by passing pageID value


You can review the source files for more info. API classes are in /lib/Lampcms/Api/ folder

More API controllers will be released soon: tags, tag, users, user, answers
As well as web controller to register the client and to get clientID.

Click here to post your reply