#6797 Move API docs from sf.net wiki to Allura (with raml?)

v1.3.2
closed
Heith Seewald
allura-api (22) asf (30) sf-4 (350)
General
Dave Brondsema
2015-08-24
2013-10-25
Dave Brondsema
No

Right now the allura API docs are at https://sourceforge.net/p/forge/documentation/Allura%20API/ They should be moved to Allura itself.

We should also consider writing the API docs with RAML which looks very nice to me. Simple and readable, has composition for things like "pagination" which apply to multiple endpoints. With RAML we could also show interactive documentation with "try it live" functionality at http://www.apihub.com/

Related

Tickets: #6920
Tickets: #7633
Tickets: #7939

Discussion

  • Heith Seewald - 2015-04-23

    Anything we can use to encourage experimentation with Allura's API would be great. I think the big three options would be Swagger, RAML, or iodocs

    I've never used RAML, but it looks like a great option.

     

  • Dave Brondsema

    Dave Brondsema - 2015-06-18
    • labels: allura-api, asf --> allura-api, asf, sf-current
     

  • Dave Brondsema

    Dave Brondsema - 2015-06-29
    • labels: allura-api, asf, sf-current --> allura-api, asf, sf-current, sf-4
     

  • Heith Seewald - 2015-07-01
    • status: open --> in-progress
    • assigned_to: Heith Seewald
     

  • Heith Seewald - 2015-08-03

    I've attached the source RAML files in a single zip file that can be imported directly via mulesoft's api designer, or by your own instance.

    There is also a live API Portal that includes some extra pages (like the API overview page).

    There are still a few rough edges, but hopfully through the process of QA we can begin to refine them :)

     
    Allura-vAPI_v1.zip

  • Heith Seewald - 2015-08-03
    • status: in-progress --> review
     

  • Dave Brondsema

    Dave Brondsema - 2015-08-12
    • Reviewer: Dave Brondsema
     

  • Dave Brondsema

    Dave Brondsema - 2015-08-12

    I am looking at this and putting it into git, as well as making some updates myself.

     

  • Dave Brondsema

    Dave Brondsema - 2015-08-13
    • status: review --> in-progress
     

  • Dave Brondsema

    Dave Brondsema - 2015-08-13

    This is in git now and I've made several changes, see branch db/6797 and please review those. A few more things we should do that I'll hand back to you for:

    Followup for separate tickets:

    • cover git/hg/svn endpoints. They need some cleanup first, as they are simplistic and isn't even hooked up for svn
    • cover /p/{project}/_nav.json ? Would need to move /rest/ from the base URI into the heirarchy, but that'd be good anyway so it shows up in the UI (it seems slightly hidden to me right now)
    • maybe update POST endpoints to take json in addition to form-encoded
     

  • Heith Seewald - 2015-08-14
    • status: in-progress --> review
     

  • Heith Seewald - 2015-08-14

    The changes look really good!

    Review at: hs/6797

    You can also see the online portal here .

    Follow-up tickets: [#7965] [#7966] [#7968]

     

    Related

    Tickets: #7965
    Tickets: #7966
    Tickets: #7968

  • Dave Brondsema

    Dave Brondsema - 2015-08-20
    • status: review --> closed
     

  • Dave Brondsema

    Dave Brondsema - 2015-08-24
    • labels: allura-api, asf, sf-current, sf-4 --> allura-api, asf, sf-4
     

  • Dave Brondsema

    Dave Brondsema - 2015-12-08
    • Milestone: unreleased --> v1.3.2
     

Log in to post a comment.