search

appdotnet / api-spec

App.net API Documentation is on the web at https://developers.app.net. Source for these docs is in the new-docs branch here. Please use the issue tracker and submit pull requests! Help us build the real-time social service where users and developers come first, not advertisers.
https://developers.app.net
950 stars 98 forks source link

incorrect language in streams API documentation #129

Closed tonymillion closed 11 years ago

tonymillion commented 12 years ago

The Stream contains frames separated by \r\n. Each frame consists of a message prepended by the length of the message and \r\n. For example:

9\r\nHELLO\r\n4\r\n\r\n12\r\nWORLD!!!\r\n

Just to confirm \r and \n would be classified as 1 char not two, so surely it would be 5\r\nHELLO\r\n

And since we're dealing with delimited data like that why is the count even necessary at all since an empty line could be just as good of a delimiter

HELLO\r\n
\r\n
WORLD\r\n
\r\n
mthurman commented 12 years ago

Thanks for the feedback! This is still an early proposal for the streaming endpoint so it's definitely subject to evolution (and will probably change somehow).

That being said, we think that although the length isn't technically necessary, it makes parsing much easier when you have to manage your own memory so it will probably stick around. Some libraries will choose to use it and others won't.

Also, '\r\n' would be counted as 2 separate control characters, not 1.

tonymillion commented 12 years ago

Ok, it just seems overly superfluous.

But I wanted to make sure of this: encoded \r is "one byte" so

HELLO\r\n

is 7 not 9?

mthurman commented 12 years ago

Yeah that documentation isn't very clear right now

Each frame consists of a message prepended by the length of the message and \r\n

When I wrote the docs, I included the leading \r\n also ('\r\nHELLO\r\n') which doesn't match the above sentence.

Hopefully next week we can revisit this part of the API and work on some endpoints/develop the final format. But either way, I'll update the docs so they are at least in agreement.

kosso commented 12 years ago

Thank goodness someone else said this. I thought I was going mad counting characters ;)

Any eta-ish on this part of the API?

I'm wondering whether to roll my own push notification system based on polling for now. (urgh) thx K

On 23 August 2012 22:43, Mark Thurman notifications@github.com wrote:

Yeah that documentation isn't very clear right now

Each frame consists of a message prepended by the length of the message and \r\n

When I wrote the docs, I included the leading \r\n also ('\r\nHELLO\r\n') which doesn't match the above sentence.

Hopefully next week we can revisit this part of the API and work on some endpoints/develop the final format. But either way, I'll update the docs so they are at least in agreement.

— Reply to this email directly or view it on GitHubhttps://github.com/appdotnet/api-spec/issues/129#issuecomment-7985219.

mthurman commented 11 years ago

This has been released and the documentation has been rewritten: http://developers.app.net/docs/resources/stream/