Reconciling Different Types Of APIs And What Data They Return

I heartily agree with you that "cleanliness is not an end in an of itself". But what's so terrible about the client getting JSON or XML back from the server instead of user-friendly error messages?

Take any popular web service API as an example (Google, Yahoo, Twitter, etc.) When you call one of their API methods, you get a response that is generic and structured. Generic so thousands of different apps can all use the same API, and structured so that they can consistently pull out the information they need.

Not only does this approach let multiple clients use a service, but it lets clients and services change at different rates. You can tweak the UI every 2 days at the customer's request. The service API is free to evolve much more slowly, as they usually do.

This becomes infinitely harder when you couple the service API to a specific client implementation. And exposing multiple APIs for different types of clients leaves you way more complexity to manage. And complexity is a price you should only pay for looser coupling, not tighter coupling.

IMHO, an API should expect a structured request and return a structured response. There is a finite number of errors that can be returned, so you label them logically in the response. The client is then completely free to react in a zillion different ways to those errors.

I agree that, if it is clear that an API will only be used by a specific source/frontend, the hassle of first creating an XML or JSON structure and then evaluating this result and reformatting it into something readable is quite overkill and also crap from a performance standpoint (JavaScript receiving JSON data, parsing it and then having to apply other logic to it, for example). Also, if the structure behind the data is changed, you'd have to re-code the API AND the source receiving it.

Now, if that API will ever be used for something else, then a generic format will of course always be best.

I usually weigh out what's best for the current project in the long run. If it's a small site that will never have to talk to another source and just output a text error from an AJAX call, then that's what the API will send back. Call me a hack or lazy ;D

I agree that API's should return structured errors. I also agree that you are trying to solve two problems with one solution. I think you're on the right track, but it looks like your HTML API would do exactly the same thing as your Public API but return errors differently.

I'm not sure I would translate API errors to UI errors at all. I would argue that all data should be validated and any error messages displayed BEFORE passing it on to an API. If for whatever reason data passes validation and gets sent to an API which subsequently fails, the API should pass back something to help a developer figure out what's going on while the user just gets some generic "it failed" message. Some API's built by the big guys out there just pass back codes you need to look up online to figure out what's going on.

I think part of the issue is that the AJAX we write isn't always meant as part of an API but as Chris said, built for a specific page. I think a good analogy for a call to an actual API would be a cfquery call. Just like we don't use cfquery errors to determine UI problems, we shouldn't expect to use API errors for that either.

Ben,
Have you ever taken a look at the Facebook API? I think that they do an awesome job with it. One of the things that you will notice is that you are actually friendly on their servers. They have you send all API calls as one API call.

What I mean is that instead of sending a call for username, a call for this, a call for that, everything is sent together right at the end of the request. I am not doing a great job of describing it, but you should really take a look at it.

I would also make all of your API calls return the same data, whether you are calling internally or externally. This takes out a lot of the effort for you. Maybe you could have an optional argument that lets the app know that it is an internal call (to avoid throttling or limiting internal calls).

Thanks,
Brandon Hansen

You make an interesting point! Even if I did check availability first, it's possible that somebody will register the name before I store can it.

If I wanted to validate everything server side, I would create a page that just validates form fields (check if their empty etc) and another to call an API that attempts registration. If the attempted registration failed, I would tell the user that the name is taken. So I guess the way I would go about it is to try and validate as much as I could before sending it. I wouldn't really call the method to validate the form fields part of an "API," just a different way to validate my form. The only method I would make part of a Data API is the method to attempt registration.

Just to clarify, to check if the fields are empty or of the proper length, I'd use JS to pass that data to a page that validates it. This page, since it's used specificly for a particular form and not part of a Data API can return the errors however I find most convenient.

@PJ
Got to be careful with ajax validation. That should not be your only method of validation, but I am sure that you know that.

ok, the performance argument was irrelevant, especially when javascript is dealing with its native JSON format.

what i do for simple error handling (let's continue with the form submission from your original post) is just pass back formatted HTML that then gets outputted in let's say a modal jquery ui dialag. i.e. <ul><li>Username required</li><li>Password required</li></ul> etc.
if a dialog that tells you which fields are missing is enough, that is it.

of course, if you pass back a JSON string such as { username: "required", password: "required" } you can then loop over those objects, highlight the input fields, write additional information next to those fields, etc., but you have to define all this logic both to your backend and your javascript code.

you could also just send back all the javascript statements in the ajax response and run them through an eval() and be done with it as well ;D

there are so many ways to tackle all the different situations, no wonder you are wondering about how to best optimize the API for specific frontends. i guess you should just go with works best for you for the task at hand and not worry about accepted API standards or whatever

Although your post is very "where do the messages come from" centric, one of the things I noted is that your "public" API is on the same "layer" as your private API.

One of the things that I am instituting at our work, and use in my own framework, is that the public facing API sits on a higher layer than my private layer, or service layer. With this setup our company offers a web services API for our customers to interact with their data in our system using the same business rules and transactions as our application, all by using the same service layer. Yes, the way the customer interacts with our API is through a seperate layer, and the calls are different, but they simply defer to the layer below to execute. It has worked wonderfully so far.

To see the chart visit http://www.adampresley.com/images/software-layer-architecture.png.

Cheers!

@Adam

Link is no go.

I like the terminology of private API (acting as sort of a service layer) and public API. At work we also have a public API that sits in a different layer. In calling our own pubic API, we usually have one AJAX call to the private API, which would in turn post to the public API to store the data. We validate data twice, once at each layer. The public API generates error codes used by developers for debugging and the private API generates error messages however we want, often in the form of UI friendly messages.

In the end, I think this this might have been what you were getting at with your HTML API.

@Brandon

The link has an extra fullstop at the end after the file extension (png.)

Just remove the fullstop and the link works fine.

In both cases. My applications' view pages are handed data by the controller, and it in turn gets data from the service layer. AJAX calls in this particular case use the controller to execute calls. I do know that many frameworks prefer to put remote fascade objects on top of the service layer specifically for AJAX calls, and that's cool. In our app we define controller methods that transform results to JSON for AJAX calls, acting as a remote proxy.

Have I mentioned how much I love OOP and design patterns? :)

Funny you should be talking about this. Bob Silverberg just began a series discussing his latest framework to try to solve these validation issues: http://www.silverwareconsulting.com/

@Gareth - I took a look at it. Pretty nice.

Ben, I too have been struggling with very similar questions for a couple months. Even without AJAX involvement, I'm just questioning the way my domain objects are validated and how any errors are passed down to the view layer with friendly messages. I currently have a generic ValidationResult.cfc so I can consistently expect this object type from domain object validation throughout my app. It basically carries a success/fail property and a collection of errors. Each error item holds field, error type and error message. So, I have both a data-centric and view/user-centric error message in this collection.

To address the concern of changing UI implementations that you mentioned (your example of "Login" changing to "Username") I have a default error message for each property, but allowed for this to be easily overridden in an abstracted manner.

I'm not completely happy with this solution and I'm currently looking to abstract this one layer further. I was looking to use a separate validation definition, possibly in XML, which sounds extremely similar to Bob Silverberg's ValidateThis!, so I'll have to keep a close eye on that as well.

I should also mention that I still feel I'm on the n00b side of good OO design, so I may be way off base, but I'm trying :) As much as I've absorbed over the years, I still feel there's a tremendous amount of learning and experience to be gained still!

Cheers.

@Ben,

That does seem to "feel" right (returning raw data from the API). But could your initial idea of another layer still apply? Rather than being a separate API on the same level, maybe it's just an API facade, if you will, to handle the raw-to-interface-friendly translation. This may be a custom facade for each application/interface, or something reusable that simply has some configuration properties per application/interface. Make sense? Thanks!

Ben,

I was calling facebook rest client API. to get the auth_token, but it gives me "Incorrect signature". Tried to find in google. but no help.

error_code 104
error_msg Incorrect signature
request_args
array
1
struct
key method
value facebook.auth.createToken
2
struct
key call_id
value 1XXXXXXXXXX
3
struct
key api_key
value 4aXXXXXXXXXXXXXXXXXXXXXXXXXXXXx
4
struct
key v
value 1.0
5
struct
key signature
value c8XXXXX5XXXXXXX1da7XXXXXXXXXXX