What Goes in Source Control?

Short answer: everything! However we need some good directory structures and source control configuration to make that a really practical answer, so this article is a quick outline of my usual advice for a good source control structure for a standard web project. The examples are for a PHP project but I'm sure you could apply this to your own language of choice, also. Continue reading

Pretty-Printing JSON with Python's JSON Tool

Today's quick tip is something that was widely retweeted after my "Debugging HTTP" talk at the ever-fabulous WhiskyWeb conference last weekend. When working with JSON on the commandline, here's a quick tip for showing the JSON in a nicer format:

curl http://api.joind.in | python -mjson.tool

You need python installed, but the JSON extension is probably included, and that's all you need for this tool. The result is something like:

python-mjsontool

You can also use this approach to present JSON data that has been captured to another file, for example, it's a handy trick that I use often when developing something with JSON as a data format.

Installing XHGui

There's a new version of XHGui (well, a few months old) and it's fabulous! It's got a few new dependencies though so I thought I'd write down how I set up my version, in case it's helpful to anyone else (and so I feel like a pro next time I have to do this!). If you're not familiar with XHGui it's a fabulously easy and friendly way to profile your application; to understand which method calls in a page take the time and how many times they are made, so you can improve the performance of your application. All these instructions are for my 32-bit Ubuntu 12.10 system, hopefully they will work for you or you'll be able to adapt them as appropriate.

Dependencies

XHGui needs version numbers or fluffy animal names, because this is a really major release and quite different to what went before in both technology and in looks. In particular, it now uses MongoDB. If you're not familiar with MongoDB, it's a super-friendly NoSQL database that makes a really handy backend for this kind of unstructured data - because every run of every page will look different. Therefore you will need:

  • MongoDB itself
  • The pecl extension for mongo
  • The xhprof pecl extension (read on if you're using PHP 5.4, there's a gotcha)

Continue reading

Endpoints for HTTP Testing

While working on a book ("PHP Web Services" from O'Reilly, not out yet but soon!) recently, I was looking for some place I could make HTTP requests to, to show off how to make different kinds of requests with different tools. On my own machine, I have a couple of scripts that chatter back giving debug information about the requests that were made, but I wanted to get the tools examples going without any additional dependencies at all. I hadn't used anything like these tools before, but I found quite a few alternatives, so I thought I'd share what I came up with. Continue reading

Printing PDF Bookmarks List

I work with PDF a lot, and it bothers me that I can see an outline view when I open the document, but I don't seem to be able to grab just that view. My presentations are mostly PDF and the titles and section headings show up nicely. Today I figured out how to get an outline view, so I'm putting that information here while I remember how to do it!

I used a tool called pdftk which is excellent, I've used it before for doing various other PDF-related things. To grab metadata such as bookmarks, use the dump-data command, like this:

pdftk myfile.pdf dump_data | grep BookmarkTitle > outline.txt

The above line takes all the bookmarks from the PDF (this was a slide deck created using powerdot and LaTeX, the section and slide titles nest appropriately), and outputs a bunch of information about the document and the various PDFs. The grep command just gets the lines containing "BookmarkTitle", then the whole thing gets written to a file. I cleaned that up and now I have the outline of my course, so I can add timings, notes for the exercises and so on.

Five Clues That Your API isn't RESTful

I get a lot of emails asking me to get involved with API projects, and that means I see a lot of both implemented and planned "RESTful" APIs. Now, I absolutely love REST and for a data-driven application, it would be my first choice. A service of some other description may work better for other scenarios or skill sets, and non-RESTful services can be very, very useful. If you tell me that your service is RESTful, then I expect it to be. If you're not sure, look out for these clues:

It has a single endpoint

I don't really care what else is going on in your API, any "RESTful" API which has a statement such as "all requests are made to http://example.com/rest" is ... not RESTful. REST is all about handling representations of resources, each is represented by its own URI and we operate directly on that. If it looks like "pretty URLs", then it's probably along the right lines. Continue reading

How NOT to Design Your API

Recently I tweeted as a #linktuesday link the 10 Worst API Practices post from ProgrammableWeb. Today, in search of some concrete examples of APIs implementing unhelpful antipatterns, I sent out a tweet for help:

What's the most frustrating inconsistent/misleading bit of API you've seen? Looking for cautionary tales! Please RT
@lornajane
Lorna Mitchell

In the raft of responses (and thankyou all, this was fabulous, helpful and entertaining in equal parts!), there were some definite patterns that I'd like to share with you, in no particular order. Continue reading

You're Not Using Source Control? Read This!

Last week I wrote an email to a client who hasn't yet implemented source control, but who is thinking about it. It turned into rather a long email as I attempted to convey WAY too much information in one long email. After some twitter banter, I repackaged my thoughts into a whitepaper on Source Control entitled You're not using source control? Read This! (PDF, no registration needed).

The document goes on to talk about the available tools (git, Hg, SVN) and give a sales pitch for _why_ source control has benefits for an organisation. There are also some action points to follow to implement source control if you haven't already taken the leap, which I hope will help anyone looking to take that step - it's kind of awkward in this day and age to admit that your organisation doesn't have source control, but however this situation arose, hopefully this document wraps up my thoughts on how to find a good way out! Continue reading

Building on Datapoint: Weather With Icons

I wrote the other day about the new datapoint API from the MetOffice (there were some great links to other weather APIs in the comments, if you like weather). I've been using it to create a detailed forecast of the weather over the next few days, mixing in some lovely weather icons by Adam Whitcroft, from The Noun Project (the same site that the icons on my own site came from) - so I have something like this for each kind of weather:

noun_project_2590
Continue reading