These forums have been archived and are now read-only.

The new forums are live and can be found at https://forums.eveonline.com/

EVE Technology Lab

 
  • Topic is locked indefinitely.
Previous page12
 

Third-party documentation discussion

First post
Author
Previous Topic Next Topic
CCP FoxFour
C C P
C C P Alliance
#21 - 2015-02-17 09:14:59 UTC
Arg, spent some time last night playing around with documentation on read the docs last night: http://eveonline-third-party-documentation.readthedocs.org/en/latest/

Source here: https://github.com/Regner/eveonline-third-party-documentation

@CCP_FoxFour // Technical Designer // Team Tech Co

Third-party developer? Check out the official developers site for dev blogs, resources, and more.
Ortho Loess
Escalated.
OnlyFleets.
#22 - 2015-02-17 15:01:43 UTC
CCP FoxFour wrote:
Arg, spent some time last night playing around with documentation on read the docs last night: http://eveonline-third-party-documentation.readthedocs.org/en/latest/

Source here: https://github.com/Regner/eveonline-third-party-documentation


Good work, and looks nice.

I've added some bits and made a pull request. Largely to test out the workflow, but also took the opportunity to get it that little bit closer to complete Big smile
CCP FoxFour
C C P
C C P Alliance
#23 - 2015-02-17 15:36:57 UTC
Ortho Loess wrote:
CCP FoxFour wrote:
Arg, spent some time last night playing around with documentation on read the docs last night: http://eveonline-third-party-documentation.readthedocs.org/en/latest/

Source here: https://github.com/Regner/eveonline-third-party-documentation


Good work, and looks nice.

I've added some bits and made a pull request. Largely to test out the workflow, but also took the opportunity to get it that little bit closer to complete Big smile


Merged it. Once I get a bit more of a feel for this and if I decide this is the way to go I will move this to the ccpgames github organization. Any commits made now will should make it over fine though as I will just push the repo there. Just an FYI. :)

@CCP_FoxFour // Technical Designer // Team Tech Co

Third-party developer? Check out the official developers site for dev blogs, resources, and more.
Calavoow2
Royal Amarr Institute
Amarr Empire
#24 - 2015-03-11 15:18:03 UTC  |  Edited by: Calavoow2
Today I came across Swagger: http://swagger.io/ which is used to document REST APIs at a multitude of companies (e.g. Riot). Because the specification is formal, it can be used it to generate API libraries for interaction (https://github.com/swagger-api/swagger-codegen). If you're lucky, there is already support for generating api docs as a server add-on. Although a public effort may produce better results.

The one thing that prevents this, is that the endpoint urls have to be known (and fixed). But in the CREST docs it is claimed that
Quote:

All resources are reachable from the root API entry point URI. Clients should not construct URIs, but instead follow URIs included in representations they have received. URIs may be stored as bookmarks, shared in IMs, sent as emails and published on web sites. CCP will endevour to support URIs as permalinks, but client applications should be able to cope with URIs becoming invalid as the API evolves and resources may be served from different locations just as web browsers cope with broken links.

Which is kind of inherently contradictory (not construct urls, but you are allowed to save them and they are permanent?).
What are your thoughts on this?
Ortho Loess
Escalated.
OnlyFleets.
#25 - 2015-03-11 16:50:20 UTC
Calavoow2 wrote:
Which is kind of inherently contradictory (not construct urls, but you are allowed to save them and they are permanent?).
What are your thoughts on this?


I think what it's trying to say is that they can't stop people from saving URLs, so will try to make them as permanent as reasonably possible. However your app should not rely on this (ideally), as they are not guaranteed permanent (and there is a mechanism to let you avoid storing deep links).
Zifrian
The Frog Pond
Ribbit.
#26 - 2015-03-22 19:50:23 UTC  |  Edited by: Zifrian
Thanks for posting this. I'd be interested to know what happened at Fan Fest on this topic and I'd be willing to help as best I can.

To me, the most important thing is simply getting everything in ONE location and using it. These forums are great but the information is scattered all over and get's lost. Right now the most confusing thing I think is that there is an EVE Wiki, these forums, a Developers page, and now you are building a new site. Not to mention other spatters of info on the API and other things at EVE-ID.net. I don't care what one is used as long as it is THE OFFICIAL place to get documentation, meets the needs of CCP/dev community, and all other CCP built references deleted after incorporating the data into the final location.

If I had my way, I'd put it all in the EVE Wiki, since all other information is there. I did an update to the wiki for CREST, which is here: https://wiki.eveonline.com/en/wiki/CREST_Getting_Started Appreciate any feedback but I think this is a decent start from the data I know and have links for.

The other thing that I think is important is to make sure that it's written as simple as possible. I work in the Federal government and many of our documents become these bureaucratic hodgepodge masses that is half acronyms and the rest conjunctions and a few adjectives. Programming and development can get like that where when you write something, you assume that "everyone" knows what You are talking about. Sure you can't hold people's hand but there are many questions about things CREST that some people seem to know and a lot of others have no clue about.

Let me know how I can help. I'm not really up on all the advances in programming these days but I'm sure I can contribute something based on the work I've done that will help the readability and access to information.

Maximze your Industry Potential! - Download EVE Isk per Hour!

Import CCP's SDE - EVE SDE Database Builder
Jon Dekker
Dekker Corporation
#27 - 2015-03-23 03:01:19 UTC  |  Edited by: Jon Dekker
I just looked at the documentation, which is created by mkdocs. As long as it's on a github somewhere, we can start contributing. I agree with above, if there's a list of the api endpoints and what their purpose is, we can document it and submit pull requests.
Ortho Loess
Escalated.
OnlyFleets.
#28 - 2015-03-23 08:41:16 UTC
It's on FoxFour's GitHub atm and you can fork and submit pull requests there. Once he's sure it's the right way to go it'll be moved over to the CCP GitHub. (All history/pull requests etc is kept)

https://github.com/Regner/eveonline-third-party-documentation

The videos of the sessions aren't up yet, but third party tools was definitely recorded, so keep an eye on YouTube.

There's some new (read-only for now) endpoints coming to crest. Iirc, including mails and standings. There was an interesting explanation of the reasons crest has been delayed so much. At that point my memory fails me completely, but the video should fill in the rest when it goes up.
Hel O'Ween
Men On A Mission
#29 - 2015-05-01 13:13:56 UTC
First of all: I vote for a sticky for this thread.

OK, tried my hand on the XML endpoints, AccountStatus to start with: https://github.com/HelOWeen/eveonline-third-party-documentation/blob/master/docs/xmlapi/endpoints.md.

Comments/suggestions?

EVEWalletAware - an offline wallet manager.
Ortho Loess
Escalated.
OnlyFleets.
#30 - 2015-05-01 16:51:50 UTC
I had a quick look when the notification popped up. Looks like a good start from what I saw, not got round to pulling it so I can see it rendered properly yet though.
Hel O'Ween
Men On A Mission
#31 - 2015-05-02 11:39:34 UTC
Ortho Loess wrote:
Looks like a good start from what I saw [...]


OK, so I'm not completely off track. Big smile

One thing I was thinking about is if each endpoint would benefit from a short, textual description of its purpose, i.e. "AccountStatus provides information about the player's EVE Online account, such as account creation time and remaining subscription time."

As it stands now, someone completely new to the API has to figure the purpose of each endpoint out by trying to make sense out of the query parameter/result descriptions. Just recently some longtime 3rd party dev recognized that player outposts can be pulled from the API with the wonderful obvious name "ConquerableStationsList" ...

EVEWalletAware - an offline wallet manager.
Ortho Loess
Escalated.
OnlyFleets.
#32 - 2015-05-03 18:31:43 UTC
Hel O'Ween wrote:
One thing I was thinking about is if each endpoint would benefit from a short, textual description of its purpose, i.e. "AccountStatus provides information about the player's EVE Online account, such as account creation time and remaining subscription time."


Yes, that would definitely be a good thing to add.
Hel O'Ween
Men On A Mission
#33 - 2015-05-04 09:45:38 UTC
Yeah, will do so eventually, as soon as FoxFour provides some feedback/merges the changes (hint, hint) ...

EVEWalletAware - an offline wallet manager.
CCP FoxFour
C C P
C C P Alliance
#34 - 2015-05-04 10:55:17 UTC
Hel O'Ween wrote:
Yeah, will do so eventually, as soon as FoxFour provides some feedback/merges the changes (hint, hint) ...


;) Sorry, it was a long weekend here. Back in the office now and hope to review it later today. :)

@CCP_FoxFour // Technical Designer // Team Tech Co

Third-party developer? Check out the official developers site for dev blogs, resources, and more.
Hel O'Ween
Men On A Mission
#35 - 2015-05-04 12:34:40 UTC  |  Edited by: Hel O'Ween
CCP FoxFour wrote:
Hel O'Ween wrote:
Yeah, will do so eventually, as soon as FoxFour provides some feedback/merges the changes (hint, hint) ...


;) Sorry, it was a long weekend here. Back in the office now and hope to review it later today. :)


No worries, take your time. As it's supposed to be "official documentation" better make sure to get it right right (that's two "rights", right?) from the start and have a really close look at it.

EVEWalletAware - an offline wallet manager.
Previous page12