Developer FAQ

From Plings Info

Contents 1 Plings Input API 1.1 General Questions 1.1.1 How often should I be submitting data to the API, and how far into the future should events be published? 1.1.2 I've got more data than the API asks for. 1.1.3 I want to refernce an original data source, how would I do that? 1.1.4 What about a field for x,y,z? 1.1.5 What if the API changes will I have to scrap everything and start again? 1.2 Categories and Keywords 1.2.1 What are Categories and Keywords? 1.2.2 Can I get a list of the keywords? - I'm building a search tool.. 1.2.3 Can I do a keyword search on the data using theAPI? 1.3 SOAP 1.3.1 ASP.NET service has trouble connecting to Plings 1.3.2 I've got problems adding Venue data. 1.3.3 I keep being told that non-mandatory fields are required. 1.4 HTTP POST 1.4.1 How do I delete an activity? 1.4.2 How do I update an activity 2 Plings Output API 2.1 I've got some development data in, how do I see it using the output API? 2.2 Links in the RSS feed don't go to my activity. What gives?

Plings Input API

General Questions

How often should I be submitting data to the API, and how far into the future should events be published?

As the data provider we think you are probably in the best position to make this judgement. The important thing is that the data is 'good data' - accurate, takes into account holiday sessions, updates cancelled sessions, etc.

If you say, provide a years worth of data - how accurate are the events billed for 12 months time? You may have some fixed events for a years time that you want to publish now, but you may need to remeber to update that information if it is cancelled or needs further information adding.

Many programmes run term-time only, and leaders may well plan these sessions 3-4 weeks in advance of them taking place.

If you can publish at the point of creation, then that might be a good thing to do.

Technically, the API can accept large amounts of data quite frequently, so it's up to you as to whether you update weekly, daily, monthly. It just depends on how that chosen time span effects the quality of your data.

Remember, once an activity has been published to us, you don't need to publish it again, but you do have the options to remove or update it.

If you find it difficult to make an initial judgement, try publishing weekly, fortnightly or monthly, to see how that works for you.

I've got more data than the API asks for.

That's fine by us. We are trying to find the balance between keeping the data slim and getting all the necessary information. We'll take suggestions for the Plings system to accept other data, but can't promise that this will be included.

I want to refernce an original data source, how would I do that?

We might describe this as "Contextual Data":

This describes a range of data fields that it is not necessary to aggregate into Plings, and which are best served by being made available within their original context and setting. This can describe both actual data fields but also content related material – both hosted and accessed from secondary data sources. The difference here is that Plings is able to reference this data, rather than transfer it. (You would use the Activity Source field in the API to do this)

By establishing a difference between Core and Contextual data, we are able to position the central engine of Plings as lightweight, yet scalable. Equally, for data suppliers the degree of data actually needed is adequate whilst not being prohibitive.

What about a field for x,y,z?

We're always happy to hear your suggestions. We have done a lot of work on working out what we think is necessary with a whole range of partners over a number of years, but that doesn't mean we've got it 100% right!

Suggestions about the working of the API, additional fields, different ways of thinking are all welcome. We take the suggestions and discuss their merits within the team. Any changes we do make will be announced to the community through our blogs and developers google group, as well as back to the original contributors.

What if the API changes will I have to scrap everything and start again?

No! We really do not see this happening. Any changes are likely to be in order to allow you to do more with the system - this means by keeping an eye on developments you can take advantage of the latest features, while being re-assured that existing functionality will not be compromised.

Having said that, for the time being we're pretty much in 'feature freeze' at the moment, so you can expect anything you do with the current API to work for a long time to come.

Inevitably overtime there may a need to fundamentally changes to the API, but legacy support for old versions will be maintained.

Categories and Keywords

What are Categories and Keywords?

We set up Categories as a way of building a ordered classification for activities. It's proved to be a complicated affair. (see http://blogs.plings.net/?p=459 ) Currently, we suggest you use just 4 categories, that loosely fit with the Every Child Matters Framework (http://www.everychildmatters.gov.uk/aims/). They are:

• Creative and Cultured
• Entertain Me
• Get Active
• Get Involved

Keywords offer a free tagging option. Where possible these should be submitted as collections of single words. We have people working on ways of building our current 'cloud' of keywords into a useful taxonomy for describing activities.

Can I get a list of the keywords? - I'm building a search tool..

The keywords and categories associated with an activity are delivered in the appropriate feeds when you request data from Plings. At http://stockport.plings.net, we use this data to generate tag clouds as a way that people can browse to the information. We deliberately avoided a traditional search box, because all too often this can bring 'no results'.

We don't really publish a full set of the keywords that are in the system, although it is available if you really need it.

For Categories however, there is a clear list, but beware, not all data providers classify their activities this way.

Future Plans This is an area we are working on, our goal is to create a useful taxonomy for positive activity data. We're getting close to this and hope to develop it into a webservice to work with the Plings data. We do not have a time scale on this development as yet.

Can I do a keyword search on the data using theAPI?

Not just yet. Currently you would need to grab the data for the time period you are interested in and work through the data yourself to find activities tagged with the keywords you were looking for.

SOAP

ASP.NET service has trouble connecting to Plings

A few people have reported trouble with their ASP.NET SOAP services. It seems that enabling cookies on your client (these are disabled by default) will mean you can stay connected and transfer data. Typically this means adding a line:

serviceName.CookieContainer = new System.Net.CookieContainer()

where 'serviceName' is the name of your service.

I've got problems adding Venue data.

When using the SOAP service, before you can submit a 'SimpleActiviy', the venue at which this takes place must exist. This may mean creating a 'SimpleVenue' first. Once you have create a venue, then you can submit the activity with the appropriate venue id, returned to you via the service.

I keep being told that non-mandatory fields are required.

It seems with SOAP in PHP5 that all fields are required. So you may have to build your request up to include all fields - just enter 0 as the value where you have no data. (If you use the NuSOAP toolkit instead, then fields that are not delivered are just ignored. There is a conflict between PHP5 and NuSOAP however, see http://code.google.com/p/nusoap-for-php5/ for an explanation and workaround)

HTTP POST

How do I delete an activity?

Right now, you can't delete using the HTTP POST method. This is because we think it's a good idea to avoid big machine driven batch deletes. The whole issue of deleting data needs careful thought - updates may be much better. For example, if an activity is cancelled, letting people know that it is cancelled is better than having it just disappear. There is, however, a delete method available through the SOAP webservices, for when things really do need to be deleted.

How do I update an activity

Simply pass us all the data you have about that activity, along with the activity id, and we'll update the record. Currently you would use the <ActivityID> field, and use the data returned to you when you created the activity. We anticipate that this will change to <ActivitySourceID> after Easter 2009, where this value will be your own unique identifier.

Plings Output API

I've got some development data in, how do I see it using the output API?

Follow the documentation at: Plings Output API, but add:

 ?APIkey="5A605302-FC5BC526-4473C6AB-B4D9009B-RQMKMLDM"

to the request URL. This will show you data from the Development Sandbox Server.
Note: This will also work for calls such as RSS that would not normally require an API key.

Links in the RSS feed don't go to my activity. What gives?

When supplying data using the dev key, we put all your data into a development database, but use the 'live' services to feed data back to you. So an RSS call to your development data will return a link to an activity as though it were in the live dataset. Currently you get something like this:

 http://www.plings.net/index.php/a/77078 

where 77078 is the unique Plings activity ID - BUT in the development database! The link of course points to what it thinks is a real activity. Following that link will not take to the activities you have supplied.

Following