| Time |
S |
Nick |
Message |
| 00:00 |
|
|
quimrstorres joined #rest |
| 00:11 |
|
|
huckleberry78 joined #rest |
| 01:12 |
|
|
quimrstorres joined #rest |
| 02:14 |
|
|
quimrstorres joined #rest |
| 04:06 |
|
|
tbsf joined #rest |
| 04:15 |
|
|
quimrstorres joined #rest |
| 04:50 |
|
|
_ollie joined #rest |
| 05:16 |
|
|
quimrstorres joined #rest |
| 05:38 |
|
|
wsieroci joined #rest |
| 05:55 |
|
|
Macaveli joined #rest |
| 06:00 |
|
|
huckleberry78 joined #rest |
| 06:02 |
|
|
hucklebe_ joined #rest |
| 06:04 |
|
|
huckleberry78 joined #rest |
| 06:06 |
|
|
huckleberry78 joined #rest |
| 06:08 |
|
|
huckleberry78 joined #rest |
| 06:10 |
|
|
huckleberry78 joined #rest |
| 06:28 |
|
|
_ollie joined #rest |
| 06:38 |
|
|
_ollie joined #rest |
| 07:17 |
|
|
quimrst__ joined #rest |
| 08:01 |
|
|
DracoBlue joined #rest |
| 08:06 |
|
|
adsc joined #rest |
| 08:08 |
|
adsc |
I have a conceptual problem. How do you map inheritance to resources? E.g. I have a super type A, and three types that derive from it. Do I make a resource for each type? If not, how do I document the different return types? |
| 08:09 |
|
trygvis |
externally I wouldn't use subtypes at all |
| 08:10 |
|
trygvis |
what I often do is day that certain fields have are available if state=foo or certain flags are set |
| 08:13 |
|
adsc |
what do you use for documentation generation that supports this? |
| 08:14 |
|
adsc |
I have seen that swagger supports inheritance with the allof tag |
| 08:15 |
|
trygvis |
I write the documentation by hand |
| 08:18 |
|
|
quimrsto_ joined #rest |
| 08:19 |
|
adsc |
and how do you deliver it to the clients? |
| 08:19 |
|
|
leo2007 joined #rest |
| 08:20 |
|
trygvis |
html, it is deployed as a part of our application |
| 08:20 |
|
adsc |
hmmm |
| 08:21 |
|
leo2007 |
Is it REST using 'POST /cart' to create a new item in the cart? |
| 08:22 |
|
adsc |
the thing is, some of the documentation generators are really nice, they not only generate a nice html documentation for you, but they also include a test client, and some even generate API-connector libraries in various programming languages for potential clients |
| 08:24 |
|
trygvis |
yeah, I know. I find those a very nice way of making a nice RPC interface and a very bad RESTful interface |
| 08:25 |
|
adsc |
the connector libraries? |
| 08:28 |
|
trygvis |
the documentation and client generators |
| 08:29 |
|
adsc |
I can understand your argument concerning the client generators, but what is there RPC about auto generated html doc and test clients? |
| 08:29 |
|
adsc |
the test client is just a form that lets you make a request and see the response live in the doc |
| 08:32 |
|
trygvis |
I didn't deliver any arguments, just a statement :) |
| 08:34 |
|
trygvis |
the embedded test clients is not a problem. I haven't found them very useful myself (like, they almost never support authentication so instant fail), but they can work |
| 08:35 |
|
trygvis |
we embed the HAL browser in our app, but that is also just vaguely useful. but authentication work as you're already authenticated when you get the browser |
| 08:36 |
|
adsc |
I'm really just looking for a way to have an online documentation that doesn't require me to manage a detached code base |
| 08:36 |
|
adsc |
because I know that if the documentation is detached from the code, it will not be kept up to date |
| 08:36 |
|
trygvis |
yeah. which is why we have the documentation in our codebase |
| 08:37 |
|
adsc |
trygvis: so you wrote your own doc parser? |
| 08:37 |
|
trygvis |
doc parser? |
| 08:38 |
|
trygvis |
our api isn't very big so it is all hand written, but we could generate the documentation from our code if we wanted to |
| 08:39 |
|
adsc |
you just said your doc is in the codebase...if you mean the same git repo, then it's not enough for me...it has to be in the code itself, or people will change the code and neglect the doc |
| 08:39 |
|
trygvis |
right, that is not a problem for us |
| 08:40 |
|
trygvis |
I don't see how you're going to make that work in a useful way anyhow, there is so much more needed than just documentation of just the resources |
| 08:41 |
|
trygvis |
the resources itself is often quite obvious how to use, the interaction between the resources and how you manipulate them is often more complicated and hard to generate from just code |
| 08:43 |
|
adsc |
I don't want to generate the API, just the doc |
| 08:43 |
|
trygvis |
that is what I meant, generate the doc |
| 08:43 |
|
adsc |
I already have an API that's in production, and it's also manually documented, and its documentation is never up to date |
| 08:44 |
|
adsc |
developers are just too lazy to maintain documentation that's separate from the code |
| 08:44 |
|
trygvis |
this is our api: https://fiken.no/api/doc/. it is a 639 line markdown document, a liberal count of lines that could be generated says that 27% of that can be generated from code |
| 09:36 |
|
trygvis |
adsc: I see your point, but you're going to have a way to document stuff that you just can't put in code |
| 09:37 |
|
trygvis |
I find that developers don't have a problem updating the docs as long as it is easy, at least not if you do code review |
| 09:37 |
|
trygvis |
but people are different :) |
| 09:40 |
|
|
locks_ joined #rest |
| 09:43 |
|
|
searchbot` joined #rest |
| 09:45 |
|
|
trygvis_ joined #rest |
| 09:48 |
|
|
leo2007 joined #rest |
| 09:56 |
|
|
saml joined #rest |
| 10:20 |
|
|
quimrsto_ joined #rest |
| 10:33 |
|
|
rm- joined #rest |
| 11:03 |
|
|
quimrstorres joined #rest |
| 11:36 |
|
|
whartung_ joined #rest |
| 11:37 |
|
|
anth0ny_ joined #rest |
| 12:21 |
|
|
tbsf joined #rest |
| 12:35 |
|
|
leo2007 left #rest |
| 13:05 |
|
|
interop_madness joined #rest |
| 13:32 |
|
|
DracoBlue joined #rest |
| 13:37 |
|
|
Haudegen_ joined #rest |
| 13:46 |
|
|
saml joined #rest |
| 14:02 |
|
|
Macaveli joined #rest |
| 14:21 |
|
|
tbsf joined #rest |
| 14:21 |
|
|
tbsf_ joined #rest |
| 15:15 |
|
|
eschmidbauer__ joined #rest |
| 15:21 |
|
|
quimrstorres joined #rest |
| 15:34 |
|
|
Devastator_ joined #rest |
| 15:34 |
|
|
Devastator_ joined #rest |
| 15:40 |
|
|
fumanchu joined #rest |
| 15:45 |
|
|
quimrstorres joined #rest |
| 15:45 |
|
|
eschmidbauer__ joined #rest |
| 15:46 |
|
|
quimrstorres joined #rest |
| 15:58 |
|
|
bigbluehat joined #rest |
| 16:33 |
|
|
DracoBlue joined #rest |
| 16:49 |
|
|
DracoBlue joined #rest |
| 17:00 |
|
|
Macaveli joined #rest |
| 17:17 |
|
|
quimrstorres joined #rest |
| 17:18 |
|
|
fumanchu_ joined #rest |
| 17:27 |
|
|
DracoBlue joined #rest |
| 17:48 |
|
|
wsieroci joined #rest |
| 18:11 |
|
|
_ollie joined #rest |
| 18:38 |
|
|
wsieroci_ joined #rest |
| 18:50 |
|
|
fumanchu joined #rest |
| 18:56 |
|
|
wsieroci joined #rest |
| 19:23 |
|
|
DracoBlue joined #rest |
| 20:29 |
|
|
philbot joined #rest |
| 20:29 |
|
|
Topic for #rest is now #rest REpresentational State Transfer | logs: http://irclog.greptilian.com/rest/today | http://tech.groups.yahoo.com/group/rest-discuss | http://code.google.com/p/implementing-rest/ | http://en.wikipedia.org/wiki/Representational_State_Transfer |
| 20:41 |
|
|
arcsky_ joined #rest |
| 20:41 |
|
|
zama_ joined #rest |
| 20:42 |
|
|
riddle joined #rest |
| 20:42 |
|
|
sulky__ joined #rest |
| 20:42 |
|
|
`0660_ joined #rest |
| 20:47 |
|
|
Davey joined #rest |
| 20:47 |
|
|
Davey joined #rest |
| 20:51 |
|
|
zama_ joined #rest |
| 20:53 |
|
|
saml joined #rest |
| 21:43 |
|
|
riddle joined #rest |
| 21:53 |
|
|
quimrstorres joined #rest |
| 23:56 |
|
|
quimrstorres joined #rest |
