Cligs API v2 in development

[Pierre Far]

All

I just wrote this on the Cligs blog ( http://cli.gs/yREDhg ) and I
thought I get the ball rolling here. The second version of the Cligs
API is in development now and I'm looking for a discussion as to what
you'd like to see. Some thoughts to get us started:

1. What's working for you and what isn't?

2. Definitely coming to /cligs/create: HTML, XML, and JSON output.
HTML output already works.

3. A data export API. What would like to be able to do with this? What
kind of data and how would you like it formatted?

Thanks!
Pierre

[joedolson]

Well, what data is available? My interests are pretty basic at this
point - raw numbers are good; number of hits over x time period would
be nice (expressible in seconds with some shortcuts, perhaps?)

Those are the most important data for me, at the moment -

Joe

On Dec 15, 5:05 pm, Pierre Far <pierre...@gmail.com> wrote:
> All
>

> I just wrote this on the Cligs blog (http://cli.gs/yREDhg) and I

[TheCodeJunkie]

I would definitly like to be able to retrieve a list of all the
currently available cligs. Perhaps be able to send in a value
indicating how many results, at most, you would like, so you can do
"Give me the x last cligs". the url, description, creation date and
hits should be returned as a minimum

[Pierre Far]

>Well, what data is available?

Good question. The data logged for each hit is:
1. Clig ID (of course)
2. The Unix timestamp of the hit
3. The UA
4. Remote IP and remote host, resolved at the hit's time
5. Geo data: 2-letter country code, region (state), city
6. Various HTTP headers: HTTP Accept, HTTP Accept Charset, HTTP Accept
Encoding, HTTP Accept Language
7. The HTTP referer

>number of hits over x time period would be nice

This is actually a general point of discussion. Should Cligs provide
raw data and let the client do some analysis (like calculating rates)
or should Cligs also provide some basic analysis too in the API?

As the server owner and to create healthy competition, I prefer to
just serve data and leave it to the API users to develop interesting
analytics. That's a good division of labor.

What are your thoughts?

> I would definitly like to be able to retrieve a list of all the
> currently available cligs.

Clig management will be added. Here are some of the things I have in
mind (including your suggestion):

1. Clig enumeration - get a list of the cligs plus basic details. Only
cligs that are you in your account will be returned.
2. Clig creation - already there, but with more output formats like
JSON, XML, the newly available formatted HTML, plus the plain text
version. Creating vanity cligs will be supported by this API too.
3. Clig deletion - as it says on the tin.
4. Clig editing - just like the web-based editing of today. For
creating Right Clig (geotargeting) rules, a separate API may be
provided instead of lumping it with the clig editing.

Questions? Thoughts? What else would you like to see?

Thanks!
Pierre

--
Pierre Far, PhD
pier...@gmail.com

Know before your site crashes: http://SocialAlerter.com/
Webmaster and SEO resources: http://ekstreme.com
Blog of Science: http://blogsci.com
Short URLs with analytics: http://cli.gs/

[joedolson]

> >number of hits over x time period would be nice
>
> This is actually a general point of discussion. Should Cligs provide
> raw data and let the client do some analysis (like calculating rates)
> or should Cligs also provide some basic analysis too in the API?
>
> As the server owner and to create healthy competition, I prefer to
> just serve data and leave it to the API users to develop interesting
> analytics. That's a good division of labor.
>
> What are your thoughts?
>

I could go both ways...absolutely the raw data is the priority.
However, in the interest of encouraging use of the API, I do wonder
whether there's a benefit to providing some simple analytic data (the
most obvious things) as 'quick access' data.

On the other hand, the people likely to be playing with the API are
probably pretty comfortable with coming up with their own tools... ;)

[Birgit Pauli-Haack]

I'd like a method to look-up an existing cli.gs string for a
particular long URL for my account/apikey.
Some urls might be generated dynamically and we shouldn't have
different cli.gs for each request....

Of course, would like to have a choice to create a second cli.gs or
not... because, I can see that we would like to track different URL
purposes, share with e-mail, post to twitter etc...

Any thoughts on that?

Birgit
PS: just finished a plain Coldfusion Wrapper for the API just waiting
for riaforge.org to update

On Dec 15, 6:05 pm, Pierre Far <pierre...@gmail.com> wrote:
> All
>

> I just wrote this on the Cligs blog (http://cli.gs/yREDhg) and I

[Pierre Far]

Hi Birgit

> I'd like a method to look-up an existing cli.gs string for a
> particular long URL for my account/apikey.
> Some urls might be generated dynamically and we shouldn't have
> different cli.gs for each request....

That's a very good idea! Thanks!

Let me have a think about how to best implement this. I can
immediately see two ways, and so I need to decide which is best.

> Of course, would like to have a choice to create a second cli.gs or
> not... because, I can see that we would like to track different URL
> purposes, share with e-mail, post to twitter etc...

That's already available: just create a new clig, so nothing to do
here.

> PS: just finished a plain Coldfusion Wrapper for the API just waiting
> for riaforge.org to update

Good stuff! Please post a link here and I'll see about promoting it on
the main site.

Cheers,
Pierre

[Birgit Pauli-Haack]

Thanks, Pierre.

On idea I just have (probably nothing new, though) Who about using a flag on create method? If it's there, return the existing clig and if it's create a new clig...

I will post the url of the Coldfusion Wrapper as soon as it's live... and if you have a preview of the v2 of the api, that would help updating...and the time between v2 release and update of CF wrapper wouldn't be too long.

I appreciate very much your fast turn around in communication...

Birgit

[Pierre Far]

> On idea I just have (probably nothing new, though) Who about using a flag on
> create method? If it's there, return the existing clig and if it's create a
> new clig...

That's way number 3. For the record, the other two ways I hinted at:

1. A dedicated method, say /cligs/poll that is fed a destination URL
and an API key. It would return a list of all cligs in your account
associated with that destination URL.

2. Open up the clig search that's already available in the web
interface. That's a lot of work and I'm not so keen on it.

Having option 3 and option 1 is probably the way forward because they
would serve different scenarios.

> I will post the url of the Coldfusion Wrapper as soon as it's live... and if
> you have a preview of the v2 of the api, that would help updating...and the
> time between v2 release and update of CF wrapper wouldn't be too long.

You can always play with V2: just change the end point from /api/
v1/... to /api/v2/... . It has a very high chance of being broken at
any given time. There aren't any docs apart from this mailing list.

Cheers,
Pierre

[Paulo Morgado]

I'll second that.

This would be controlled in the account settings.

The user would be able to:

1. always create a new clig
2. have unique cligs per account
3. have unique cligs per app key

This could be an incremental implementation.

--
Paulo Morgado
http://PauloMorgado.NET/

[Paulo Morgado]

The statistics could be an RSS or Atom feed.

If no clig is provided, the feed would have all cligs.

If a clig is provided, the feed would have the cligs' statistics.

[Pierre Far]

I don't think it should be an account-level or key-level option, but a
request-level option. This is one of the fundamental power features of
Cligs (unlimited URLs per destination) and so it has to be deployed in
a controlled manner.

My favorite implementation at the moment is this: The /cligs/create
API is fed an extra option that asks it to return the most recently
created clig for a destination if one exists; otherwise, create a new
one. This maintains backwards compatibility too.

Pierre

[Alex]

I'm not as personally concerned about direct export options (such as
CSV or RSS) and more interested in a REST API, preferably one that
returns JSON.

Ideally there would be calls that let you:
a) get all traffic stats for the cli.gs account over a specified
period (either the previous hour, day, week, month, or a specified
interval)
b) get traffic stats for one specific clig

The Bit.ly API has a call that is similar to (b):
http://code.google.com/p/bitly-api/wiki/ApiDocumentation#/stats