Suggestions

[Henry H]

Dipity -

You may get more interest in your API if you didn't make the required
signature so convoluted and you provide some examples in other
languages like python and ruby.

Your API KEY + SECRET is pretty atypical. I'm not sure what requiring
folks to take an MD5 hash of the secret key concatenated with all the
query parameters being passed at the time of the api call provides
you, but it sure doesn't make it simple to try out the API.

I honestly sat down thinking this would be pretty straight forward,
but even your documentation is unclear as to what gets returned
(outside of the status codes). For example, how is someone supposed
to get the id of a timeline they just created through the API? Is
that returned? How does one know that based on the API documentation?

Anyways - just some suggestions. I'm not going to spend anymore time
attempting to decipher your API.

Good luck,
Henry

[Zack Steinkamp]

Hi Henry --

The MD5 hash ensures that only you (or someone you have shared the
secret with) is making the request. If someone doesn't know the
secret, they won't be able to generate the correct hash value.

The timeline ID is returned in the create and (undocumented) list
call. Thanks for the suggestion to improve the docs. Seems that will
be time well spent.

Regards,
Zack Steinkamp
dipity.com

[Henry H]

The challenge isn't with the secret, it's with generating the MD5 hash
using the secret + the query parameters to salt the key. Are you
concerned about someone guessing the secret? You already have a
developer API KEY. That identifies the developer/user. The key is
like a password. If someone knows both of these, there are probably
more serious security issues the developer needs to be concerned
about.

I'm not convinced the MD5 hash offers any additional value over the
secret key...

On Jul 13, 8:17 pm, Zack Steinkamp <theno...@gmail.com> wrote:
> Hi Henry --
>
> The MD5 hash ensures that only you (or someone you have shared the
> secret with) is making the request.  If someone doesn't know the
> secret, they won't be able to generate the correct hash value.
>
> The timeline ID is returned in the create and (undocumented) list
> call.  Thanks for the suggestion to improve the docs.  Seems that will
> be time well spent.
>
> Regards,
> Zack Steinkamp
> dipity.com
>

[Henry H]

Thanks for the response Zack.

You may help the developer community by providing a demo API KEY and
signature to allow people to try out the API quickly. This way
developers can test it out immediately without spending time
translating the documentation. It will also allow developers to debug
problems quickly since they are spending time using the API versus
spending time configuring the web service client to successfully call
the API. Some examples in other languages would also be useful - PHP
isn't the easiest language to read.

Cheers,
Henry

On Jul 13, 8:17 pm, Zack Steinkamp <theno...@gmail.com> wrote:

> Hi Henry --
>
> The MD5 hash ensures that only you (or someone you have shared the
> secret with) is making the request.  If someone doesn't know the
> secret, they won't be able to generate the correct hash value.
>
> The timeline ID is returned in the create and (undocumented) list
> call.  Thanks for the suggestion to improve the docs.  Seems that will
> be time well spent.
>
> Regards,
> Zack Steinkamp
> dipity.com
>

[Zack Steinkamp]

On Tue, Jul 14, 2009 at 5:59 AM, Henry H<appl...@gmail.com> wrote:
> I'm not convinced the MD5 hash offers any additional value over the
> secret key...

The additional value is that the authentication value is different for
(nearly) every request. If the mechanism is compromised in some way,
it is not a trivial matter for someone to make requests on behalf of
the developer. If we just passed the key in each request, if that got
out once, anyone who saw it could masquerade as that developer.

This scheme is not unique. Amazon uses a similar mechanism with their
web services, as do some Yahoo web APIs.

I understand that it is more complicated to implement than passing the
same key in each request, or doing basic HTTP auth, but we decided to
err on the side of security. Our clients who use this for their
businesses appreciate this.

-zs