In today's blog post, I want to continue the discussion on the developer portal for API programming. I mentioned that the REST based services could have code corresponding to the objects, in the parameters, requests and responses of the API that could be made available to download. When the data is xml or json, this was easily deserializable but things get quickly out of date adding to the developer frustrations especially when there is no other way to interpret why you are getting the 400 or 404s. Case sensitivity in the parameters or fields, This code that we enable to download can be easily detected as having changed and then updated unless the documentation is kept upto date. It's also common for model to be refactored into a separate assembly. So this may be already available.

There's actually some support out of box in the REST WebAPI framework to be able to populate this assembly of class definitions. Take for instance the Help Page sample generator in the Web API framework:
            Type type = ResolveType(api, controllerName, actionName, parameterNames, sampleDirection, out formatters);
            var samples = new Dictionary<MediaTypeHeaderValue, object>();

            // Use the samples provided directly for actions
            var actionSamples = GetAllActionSamples(controllerName, actionName, parameterNames, sampleDirection);
            foreach (var actionSample in actionSamples)
            {
                samples.Add(actionSample.Key.MediaType, WrapSampleIfString(actionSample.Value));
            }
Last but not the least, the error messages should go over and beyond to make it easy to use the APIs. This is because the APIs are not expected to be consumed by the non-programmer users so this is already a select audience. And the easier it is for the developer to debug and make progress on the application, the wider and easier the adoption of the APIs. This goes a long way to enable rapid development.
I also want to mention data quality as important in this post. Often a single field or type in the response is important for subsequent API calls. Therefore the data associated with it must be correct to pull up the responses in the subsequent calls. For an application development, its often a call sequence that enables a workflow. Hence this consideration will also help the developer.