Make Your API User Friendly

So, an API is by definition an application interface, meaning it should be usable by applications.  But you know who really has to use them?  People.  Developers.  And if you’re going to write an API, you should make it usable for the interfacing applications, but simple and friendly for the developers.  I don’t think I’m going to hear any argument about this.

I’m writing here to bitch and bitch and bitch about a project that is breaking me.  I expect it will be the last project I do with this company.  This API I have been tasked to consume and integrate with our own system is so difficult to work with and so brittle it is mind-numbing.

When you read their documentation, which is perpetually out of date, and see the data you are working with, the initial conclusion you get is that you literally have to write a UI as defined by their specs.  And that would be the easiest solution, but the dumbest one because then they should just write it themselves and host it for everyone instead of making an API.

The project involves forms.  We fill them out and send them the results.  However, we already have our own forms, so the integration should be as easy as taking our values and translating them to their values.  As part of the integration, they will send us a JSON file with a form definition.  This JSON file contains EVERYTHING needed to construct a UI.  It has the field names, the form control types, the validations, groups (with potentially infinite nesting), rules on groups, required attachments per field, permissions… you get the point here.  It’s not just a simple form definition.

Ok, so I parse out the groups and fields, then add mappings and translation code.  The translation code is off the rails because a “No” in our form must be converted to a “No” in their form.  And a “No” in their form is a GUID.  A GUID nested under the potential response values for a specific question.  So yeah, not just mapping questions, but mapping answers.  On a form with 200+ questions.

Then on top of this, they implement versioning.  So a form can be updated and we’ll get a new definition.  They may (and have done so) rename groups or fields or answers, which just causes the translation code to blow up.  Call me a lame programmer all you want, but I’d like to see someone effectively handle a value they’ve never seen before.  I’ll take the hit for not wrapping everything in an IF to see if the field was removed or renamed.  The timeline demanded does not permit that level of attention.

That’s only part of the troubles.  For each form we complete, we have to make multiple service calls.  Four, actually.  And today, they told me I’m supposed to be making a fifth call, even though things have been working for the 15+ test cases I’ve successfully completed so far.  Ok, that little gripe is not really about a specific API, but more about how the company itself has really created a monster in sum.

So back to the meat of the topic, the simplicity of an API.  So when you want someone to use your API, you want to make it easy.  If you are updating a child record, you shouldn’t have to specify the ID of the parent unless you are allowing that ID to be changed.  You can get everything you need from the ID of the child.  So why in this API must I provide so much data about so many related pieces when all I should have to provide is the ID of the data I am updating??  And another point: the values I’m returning aren’t updatable values anyway.  All that’s happening is the message is being fat and heavy and data is being thrown away.  Or maybe, the data is being saved and my work is saving them the effort of looking it up for themselves.  If that’s the case, then its unvalidated data and subject to exploit.  There is no good answer here.

So lets talk about the responses we have to send to this API.  It’s a JSON body with a dynamically constructed object with properties representing the fields of the form.  And although the field property has a name of UniqueID, it has to be returned in a fully-qualified manner, prepending each containing group’s UniqueID.  So if a group name changes, all fields under it change in the response.  It could have been easier to just send the UniqueID (since it is supposed to be unique, right?).  And the structure of the object, what the fuck.  Why not just have a simple array of key/value pairs.  Instead, you have some mystery object where a property may or may not exist.  It’s the same shit, iterate over properties or iterate over an array.  One can be handled in code with a class and a generic List, the other has to be done through a complex library like Newtonsoft and still results in an object that can’t really be navigated.  I get that JavaScript is taking over the goddamn world, but JS makes everything harder for no real benefit.

That’s as much ranting as I want to do right now.  Although it feels good to get it out, it doesn’t give me any improved perspective of the project or its viability.

403 XMLRPC Error In WordPress Hosted On Windows IIS (Remember Your Security Changes)

This is more of a note for myself.  Hopefully it will end up in a search engine and I’ll be able to find my own solution when this happens again.

Yesterday, I went to post something to one of my blogs that I self-host on a Windows server.  You’re on one of those blogs right now, go figure.  And when I did, I got a very common error: 403 Forbidden when accessing the xmlrpc.php file.  But, I had just successfully posted two days ago!  What could have changed?

I connected to the server and updated the permissions on the folder, since that is usually what 403 means.  That didn’t fix it.  I did an IISRESET.  That didn’t fix it.  I did a full reboot.  That didn’t fix it.  I kept searching for information.

When you search for WordPress and xmlrpc, you get a crap-ton of results that warn of the dangers of leaving this file exposed.  It’s a gateway for hackers!!!!!!  It’s so hackable!!!!!  Turn it off!!!!  Disable any remote capabilities to WordPress!!!!  These warning are geared toward users who use and reuse weak passwords.  Of course there is authentication on anything xmlrpc does, so if you’re getting hacked, it’s your fault.  Granted, there’s no protection from a hacker brute-forcing your xmlrpc URL until it finally hits something, but again, strong, unique passwords, people!

With that little rant out of the way, I do recognize the high sensitivity of this file.  It would not be unlike me to take some extra precautions on it.  And that’s exactly what I had done, and what I had forgotten I’d done.

I set up an IP address restriction on just that file, so only my home PC could access it.  That makes sense since I only post using Live Writer from home.  However, my IP address from my ISP changed in the last couple days and I didn’t notice.  This is how I fixed it.  If you instead want to use this info to secure your own WP site (and forget about it until your IP changes), go ahead.

In IIS, I navigated to the xmlrpc.php file in the content view

Annotation 2020-04-19 111349

After highlighting the file, I right-clicked and chose Switch to Features View.  You can see the specific file name is in the title.  I chose IP Address Restrictions

Annotation 2020-04-19 111727

And in here is where I added/changed my home IP address.  You can find yours at https://www.whatismyip.com.

Annotation 2020-04-19 112011

And as you would expect, I am able to post to blogs again, as evidenced by this post right here.

TFS 2010 to TFS 2012 Express

Last weekend I did a full upgrade on my computers to Windows 8.  Along with that, came the upgrade of Visual Studio 2012 and SQL Server 2012, and Team Foundation Server 2012.  My plan was to have a completely fresh development environment, with no legacy 2010, 2008, 2005 versions.

This was a good plan, but I had one reservation.  In this year, I converted from Visual Source Safe to TFS 2010, and now I was going to have to upgrade again to TFS 2012.  Everyone understands how to manage a big file system structure like VSS, but TFS might be a mystery.  Actually, it’s much easier.  It’s just two SQL databases.  So I backed up those databases and did my full, fresh install.

Now I’m ready to install TFS 2012, but what about my data?  I’d seen many blogs and articles describing the upgrade process.  Every one said, uninstall TFS 2010, then install TFS 2012.  But I didn’t want to have any TFS 2010 bits on the new install.  So in order to get the database instance to restore my TFS 2010 data, I installed TFS 2012, then uninstalled it.  Then I restored my TFS 2010 data into the SQLEXPRESS instance TFS created.  Finally, I reinstalled TFS 2012, selecting the “Upgrade” option, which converted my TFS 2010 data to the new schema. 

Sounds like a roundabout solution but it worked without any problems and without resorting to older product installs.

My, How Big You’ve Grown

image_thumb

There used to be a time when SQL Server was a database engine.  Setup of the product was easy.  You told it where to install, then you set up the service accounts.  Over time, the feature set of SQL Server grew and it became more of a suite of products.  This involved some more installation steps with more information to be gathered.

Somewhere around 2008, a significant change occurred with the SQL Server setup.  It involved pre-install checks, rule checks, confirmations, and other stages that significantly slowed down the install process.  What used to be a two minute wizard is now a process that can easily consume 15 minutes.  Add to the mix the growth of the feature set of SQL Server and the full install could take hours.

Following along the left of this post is a screenshot of the setup process.  We have three rule checks, one before you start, one after choosing the features to install, and one after you configure the features you want to install.  For my install, I chose “All features with defaults” thinking it would be the fastest and easiest.  Nope, I still had to run through all the steps.

The most annoying change to the install process is the rule checks.  Even if everything checks out, you still have to click Next on the wizard.  If it’s all good, why do I need to review it?  As mentioned before, this happens three times during installation.  It’s almost as if the setup program is saying, “Look at how hard I’m working.  See, I made you a big list of everything I did.”  It’s like an employee that isn’t confident of his work and has to document everything he does to justify what he’s done.

The feature growth of SQL Server has become outrageous as well:  Analysis Services, Reporting Services, Distributed Relay, Failover Clusters.  I would be very interested in seeing if SQL Server Express is selected more often just because the feature set is more realistic for most projects.

I am also curious to see if this post’s text is longer than the installation steps for SQL Server.  And I even tried to be more verbose so I could fill space.

And as it turns out, I didn’t write enough and the next post continued right next to the image.  I guess that’s a slight issue with the WordPress theme template.

Reboot 2012

It seems every year around the holidays, the 700cb family of websites gets some attention.  Most likely because that is when the hosting account renews.  This year, the sites have moved to their own server, which allows much more flexibility in what can be installed, configured, managed, and broken.

Since the loss of my blog hosted on the former SOAPitStop.com, I haven’t had an outlet for technical postings.  Now that I have this blog available on the 700cb server, I will repost many of my former SOAPitstop posts (from 2007-2009) as well as some more recent posts I’ve created on a corporate Intranet.  You’ll find a distinct difference in tone and delivery since the SOAPitStop posts were written for the public while the Intranet posts are for close coworkers.

So, like rebooting a computer, this is an opportunity for a fresh start, with renewed performance.  Welcome to the new 700cb blog.

We Have A Problem

It’s always fun to see an error message you’ve never seen before – even after using a product for almost 10 years.  While trying to check the value of an object while sitting at a breakpoint:

Cannot evaluate expression because we are stopped in a place where garbage collection is impossible, possibly because the code of the current method may be optimized.

Microsoft has very strict guidelines about the verbiage used in their programs.  I can’t believe they let an error message pass through using the word “we” in it.  It’s good to know that the .NET compiler feels that we’re all in this together.  Additionally, the use of the word “impossible” and the vagueness of “possibly because” and “may be” are very out of place.

I’ve never seen an error message so clearly state “That absolutely cannot be done.  I know why, but I don’t know why.”