API Documentation with IODocs

I write a lot of APIs, and I also preach that your API isn’t finished until it has excellent documentation. Which is great, but that means I therefore have to lead by example and document my APIs :) Enter iodocs from the talented folk at Mashery.

Iodocs is a node.js application (which is fun for a PHP developer. Most developers write a bit of JS, but this one hasn’t). You describe your API and all its methods in JSON, and then iodocs presents an interface for you to enter API keys, add parameters to each request and press the “try it!” button. This makes your API call and shows you the results on screen, which seems like a great way to demonstrate what all the various parameters do!

iodocs screenshot
Continue reading

Do Open Source with Git and Github

This article originally appeared in the May 2012 php|architect magazine.

Often I find absolutely competent programmers, who aren’t involved in open source, either because they don’t know how to approach a project, or because they just aren’t sure how the process even works. In this article we’ll look at one example, the conference feedback site joind.in, and how you can use GitHub to start contributing code to this project. Since so many projects are hosted on github, this will help you get started with other projects, too.

The tl;dr Version for the Impatient

  1. Fork the main repo so you have your own github repo for the project
  2. Clone your repo onto your development machine
  3. Create a branch
  4. Make changes, commit them
  5. Push your new branch to your github repository
  6. Open a pull request

This article goes through this process in more detail, so you will be able to work with git and github projects as you please.
Continue reading

Posting Raw Data with Curl

This week I’ve been working on a feature which handles an incoming API call from an external source (actually Paypal’s IPN service). Making external calls into my development platform isn’t how I usually work, so instead I captured the body of the request that was being sent, and replayed it against my local script using curl.

I put the data into a separate file, data.txt and then used curl to direct that data at my local URL:

curl -X POST http://localhost/app/test.php --data @data.txt

I find this approach useful for testing, but since I had to look up how to do it, I thought I’d put it here for reference!

The Quest for a Payment Gateway

Although I’ve been “making websites” for a lot of years, I’ve mostly avoided the kind where people actually pay for anything. The result of this is that I built Bitestats (elevator pitch: sign up and get a printable summary report of your web stats every month by email) but then got busy and never built the bit where people can actually pay to use it.

I recently carved out some time to correct this situation, and fell into an absolute pit of confusion when I tried to figure out what my options even were. My requirements are that my customers are global, I am UK-based, people will set up a regular subscription, and I don’t have (and I think I don’t want) a merchant account at this point. I’m not PCI compliant and have no intention ever to attempt that. This post is an attempt to round up some things I found out along the way. Continue reading

Two Years of Trading

Two years ago I quite literally gave up the day job. I had no clients, no experience of being anything other than a salaried employee, but I did have an urgent need for change! Two years on I’ve just done the end-of-the-year reporting and I’m struck by how far I’ve come and how much the numbers surprise me (there are no actual numbers in this post, it doesn’t feel appropriate somehow – but there are graphs!). Continue reading

Lesson Learned: Look in the Pull Request Queue

If you follow me on twitter you might have seen some overexcitement when I managed to edit and compile a vala application recently. I use a great deal of open source tools, but many of them don’t seem open to me, because I don’t have the skills to modify the code. Regardless of that, it’s still vitally important that it is open (this is a whole other post and I’ll avoid that tangent right now). Continue reading

Monday Git Tips

One project I’m working on at the moment involves finding my way around changes in a codebase that isn’t mine – and it’s quite large. I was doing pretty well with a combination of git log and git show and in particular two of my favourite existing tricks:
Continue reading

Pushing to Different Git Remotes

Just a quick tip because I’m working on a different git workflow at the moment with one of my clients, and it struck me that this usage pattern is something I don’t usually write or speak about at all. Most git setups have one “main” repository, and either:

  • there is a gatekeeper that manages merging to here
  • all developers have write access

In this case, I’m working with the second option, so I’m pushing to the upstream repo. I’m also pushing to a live repository as well, so I thought I’d outline the commands I’m using. The setup here is the main github repo, and I have my own fork of that, which is cloned onto my laptop. I can push to both that main repo, which I’ll call “upstream” (because the github documentation does and it makes sense!) and another repo that I’ll call “live”. All in all it looks something like this:


Continue reading

Downloading Files from Faspex

This week, someone sent me a very large file using something called faspex. To begin with, it sent me a link to click on to download my file, but then started telling me “for best results, install a plugin”. And apparently “for best results” means “to download this file in any way”.
Continue reading

How the Web Looks to Me

It feels like I’ve tried to field the question about how I can use the web without using a mouse (or trackpad or equivalent), without “pointing”, multiple times in the last couple of weeks. The answer is quite visual so I thought I’d share. This is how the web looks to me:

I navigate the web using the Keyboard Navigation extension in Google Chrome, which is what is adding all the little labels you see in the screenshot above. Install the extension, and press comma. The labels will pop up, then you type whichever character(s) show next to the thing you want to “click” on, and off you go.

It’s super-simple, and easier to use than I expected. Why don’t you try it out on your own sites? You’ll get a sense of how the web looks from where I’m standing :)