API Schema

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.

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 SummersOn 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.

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/

+1 on the docs being below parOn 22 June 2014 22:18, Nic Wise nicw@fastchicken.co.nz wrote:

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:

https://github.com/nicwise/freeagent

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.

Nic

On 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/


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.

Jon Free

WasteSource

07931 925257 | 0117 205 0259

wastesource.co.uk http://www.wastesource.co.uk/?footer=jf | @wastesource
https://twitter.com/#!/WasteSource

Loft 3, Tobacco Factory, Bristol, BS3 1TF

Information in this email is confidential and intended for the sole use of
the addressee/s. Access, copying, disclosure or re-use, in any way, of the
contents of this email by anyone other than the addressee/s is
unauthorised. I accept no legal responsibility for the content of the
message. If you have received this email in error, please return it to the
sender.