When someone orders stuff from Fox Box I get a notification email with the details. It’s functional but ugly. More to the point it’s not formatted for label paper of any kind. Something like this:
You have received an order from Ben Fox. Their order is as follows:
=====================================================================
Fox Box
admin@fox-box.co.uk
ORDER #: 2588 Date: September 16, 2012
=====================================================================
1 x Ork Warbike 2 (#912) - £2.50
The original invoice generator I wrote was both impressive and hacky. It would query the MySQL database, find the relevant order information, decode it, and spit it out onto a template. There may well have been a better way of getting information out of a WordPress database but that was a can of worms I was not going to open.
Unfortunately by doing things this way I was locked in. As soon as the order information format changed the script broke. Annoying but to be expected, really.
It was one of many reasons I held off upgrading to JigoShop 2.x. Luckily I held off long enough that JigoShop 2.1 was released and it included an API. An API is essentially a convenient way of talking to a program. Instead of dealing with the internal workings it offers a load of convenient ways to get information in and out of the program.
The main problem I ran into with all this is the fact that, like many other things, the documentation explaining how to use it was written for people that already know how to use an API. I don’t expect it to explain the basics entirely but a simple “Don’t know what this means? Head over to [SITE] and take a look at their API tutorial.” would have helped a great deal.
The first major problem was this: where is the API?
The documentation talks about https://jigoshop.dev/api/v1/orders/:id
Initially I thought this meant that my JigoShop instance would contact their servers to act as a middleman. Nope.
There’s nothing in my files at https://fox-box.co.uk/api/v1/orders/:2588 either – it just throws a 404 error. I did find https://fox-box.co.uk/wp-content/plugins/jigoshop-ecommerce/src/Jigoshop/Api.php/v1/ but that seemed to be a dead-end too.
I posted a topic about this over on the support forum but didn’t get an answer so eventually I emailed them to ask. It turns out that it is at https://fox-box.co.uk/api/v1/ but other bits of syntax were wrong. That colon? Yeah, that’s not supposed to be there. Not a clue why it is, convention I imagine.
If you try visiting https://fox-box.co.uk/api/v1/orders/2588 you’ll get a blank page, not a 404. That means it’s working – but you don’t have authorisation to view the page. Further proof that it’s working can be found here: https://fox-box.co.uk/api/v1/ping
{"success":true,"time":1494332877}
That’s what we’re after! JSON encoded data! Nearly everything can easily process JSON and it’s quite easy to read without being a computer too. It’s just a load of “Variable name”: value – e.g. “name”: “Fox Box Frankenork”. So now it’s just a matter of how the bloody hell authorisation works.
To people who know about APIs this is probably very easy stuff but for me it was a matter of trying to figure out how complex the problem is. APIs are usually aimed at developers and so the idea might have been that I was expected to code up something complicated that exchanged keys or did a special handshake or something.
The documentation was… unhelpful. On my end I had a username, password, and “secret key”. The documentation told me I was supposed to pass a header with “Authorization: Bearer [token]” and then sort of wandered off to have a smoke or something.
After trying various things I eventually figured out that by sending over the username and password it would send back a temporary token. I’d then use that token in future requests. Eventually it expires and a new one is needed.
So I’d send:
curl https://fox-box.co.uk/api/v1/token -X POST -u user:password
The server would send back:
{"success":true,"token":"[censored]"}
Then I’d use that token to ask it for details about order 2588.
curl https://fox-box.co.uk/api/v1/orders/2588 -X GET -H "Authorization: Bearer [censored]"
Lo and behold I’d get this lot back!
{"success":true,"data":{"id":2588,"number":"2588","created_at":{"timestamp":1347833013,"format":"2012-09-16 22:03:33"},"updated_at":{"timestamp":1493123797,"format":"2017-04-25 12:36:37"},"completed_at":{"timestamp":1347833059,"format":"2012-09-16 22:04:19"},"items":[{"id":null,"key":"2a9d121cd9c3a1832bb6d2cc6bd7a8a7",
Then it was just a matter of figuring out how PHP talks to cURL (a little bit fiddly but not too bad) and sticking the relevant bits of info into the right places on the old form.
So the old code might say:
echo $order_details_unserialized['shipping_address_1'];
The new way of storing order information doesn’t have address_1 and address_2, just address so the new code just says:
echo $shipping_details['address'];
Admittedly I also took the time to write a bit of extra code that would format addresses more appropriately for some countries. Lots of places use what I think of as the “European” style of address (Postcode – City rather than a separate line for the postcode) so the new system should result in better labels too now that it takes those into account. Similarly the US has state initials before their zip codes.
I’d show you the result but seeing as examples contain personal details there’s not much left after I’ve censored them!
Right, back to pouring resin into hollow blocks of silicone.
Yesterday we packed our bags (six bags in total with one dedicated solely to snacks and lunch options) and took a hire car to Ecclesfield School in Sheffield — the venue for the first ChillCon gaming convention. We set up shop (pardon the pun) in the sports hall along with twenty-odd other traders and got ready for a full day of wargaming fun!
