Hi Murray and Nick
Throwing in my 2c. Or 2p, depending on where you are.
I’d like to see the format of the docs change a little. I’d love to
see them something like this (note: you have some of this already!):
eg for /invoices
Short description of what the endpoint is.
Description of the main data type, including possible values for enum
types (this you DO NOT have)
Examples of the various verbs (get, put, post etc - this you have)
- With required fields if creating a new item
Gotchas. eg if I just UPDATE an invoice, but don’t include lines, does
this kill the lines which are already there?
The main one is the main data type with possibly values, which I’d
hope could be generated from source annotations.
BTW, if you need a (fairly complete) .NET client, I have one here:
I use it on mobileAgent. Needs RestSharp (which I’m planning on
getting rid of and moving it to using HttpClient, but not any time
really soon), but should work in both the desktop/full framework
environment and Xamarin/mobile.
NicOn Fri, Jun 20, 2014 at 9:57 PM, Murray Summers murray@freeagent.com wrote:
Hello Nick,
Thank you for your feedback.
We do realise our documentation isn’t up to scratch and have heard similar
feedback from other developers. We will be improving our API documentation
in the near future and we are hopeful this will make life easier.
We always welcome developers pointing out mistakes in the documentation and
will update documentation as soon as possible. If you have any specifics
that you can share this would be greatly appreciated.
Cheers,
Murray Summers
On Thursday, June 19, 2014 10:33:57 AM UTC+1, Nick Dodd wrote:
Hi,
I have been using the FreeAgent API within a .NET application and I have
noticed on occasions that the online documentation for the resources doesn’t
match what is sometimes returned. This means I have to determine what is
actually returned by executing manual queries for each resource to get a
list of the properties, which both time consuming and frustrating.
Additionally, your documentation doesn’t specify the data type for a
property, which again needs to be manual identified and sometimes guessed.
I appreciate that with FreeAgent evolving as quickly as it is, it can be
difficult to keep documentation up-to-date, but have you considered some
kind of automated schema that can be downloaded on demand that describes the
latest data setup for each resource? One of your competitors seems to have
nailed this with a XML schema that can be downloaded so objects can be
automatically generated.
https://developer.crunch.co.uk/api-documentation/api.xsd
I personally don’t think it is a big task to get such a utility in place
and would make your API much easier and friendly to use.
Nick.
–
You received this message because you are subscribed to the Google Groups
“FreeAgent API” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to freeagent_api+unsubscribe@googlegroups.com.
To post to this group, send email to freeagent_api@googlegroups.com.
Visit this group at http://groups.google.com/group/freeagent_api.
For more options, visit https://groups.google.com/d/optout.
Nic Wise
t. +64 21 676 418 | @fastchicken
b. http://www.fastchicken.co.nz/