What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 133 Stack Exchange communities.

I was just going through the pile of SE websites and just found Stack Exchange API. The documentation for each REST endpoint or URL is given in detail. Also, the API methods are listed and a separate page is given to describe each REST endpoint.

  1. API Methods:

    enter image description here

  2. Individual Method Description:

    enter image description here

Stack Exchange is built using C#, ASP.NET MVC evident from this answer., and many other technologies. What language is the Stack Exchange API written in?

If it is written in C#, then what tools are used for documentation? How is the documentation created?Are they using only XML comments or some library?

share|improve this question
2  
They do have a mild case of NIH, so it's probably a custom solution. It works for them, they usually create something much better than what is already out there. –  Cody Gray Aug 2 '13 at 6:05
    
@CodyGray "they usually create something much better than what is already out there", no doubt about that. I am curious how such documentation is built. It's awesome.. –  Bhushan Firake Aug 2 '13 at 6:08
    
Speaking of the API, I wish that it wasn't only read only off of the site, a true SE App where you could post questions and answers would be amazing. –  Pip Aug 4 '13 at 2:16
    
Wouldn't this mess with some ad agreement SE has? By doing that you allow some API client to bypass the ads and create an ad-free SO or worse, a SO app that advertises competitors of the SO advertisers... I'm sure the answer is along those lines... –  retailcoder Aug 4 '13 at 6:08
    
Any answer on this? –  Bhushan Firake Aug 5 '13 at 4:43
    
@retailcoder not sure what you mean. You mean the API itself? Bypassing SO's ads is easy by using the data dump, you are explicitly allowed to set up web sites with SO's content in direct competition. –  Pëkka Aug 5 '13 at 8:26
1  
"Stack Overflow is built using C#," should be "Stack Exchange is built using C#," –  hjpotter92 Aug 5 '13 at 8:32
1  
@hjpotter92 Yeah ...amended my question for this correction... –  Bhushan Firake Aug 5 '13 at 8:34
    
@Pekka웃 that was for TheProgramm3r's comment regarding posting content, not just consuming it. But yeah would be nice. –  retailcoder Aug 5 '13 at 12:35
    
Maybe they use C#'s XML comments? –  Cole Johnson Aug 5 '13 at 12:40

1 Answer 1

up vote 3 down vote accepted
+50

The Stack Exchange API is a .NET MVC4 app written in C# 4 (technically 5 now, but it isn't using any async/await stuff).

The index page is just a view, maintained more or less by hand.

For methods there's nothing magic there, it's just a collection of views with a common master. A similar approach is taken for types.

Here's (most of) the view for /answers

@{
    Layout = "~/Views/Documentation/Method.cshtml";
}

@section MethodName { /answers }

@section Discussion
{
<p>Returns all the undeleted answers in the system.</p>

<p>The sorts accepted by this method operate on the follow fields of the <a href="/docs/types/answer">answer object</a>:
    <ul>
        <li><strong>activity</strong> &ndash; <code>last_activity_date</code></li>
        <li><strong>creation</strong> &ndash; <code>creation_date</code></li>
        <li><strong>votes</strong> &ndash; <code>score</code></li>
    </ul>

    @(DocsTypeDescriber.DefaultSort<AnswerSort>())<br>
    <br>

    It is possible to <a href="/docs/min-max">create moderately complex queries</a> using <code>sort</code>, <code>min</code>, <code>max</code>, <code>fromdate</code>, and <code>todate</code>.
</p>
}

@section Type
{
    <p>This method returns a list of <a href="/docs/types/answer">answers</a>.</p>
}

@section ConsoleParameters
{
    @{
        var param = ApiParameters.DescribeWithSort<AnswerSort>();
        var filterName = ApiFilter.Default.EncodeFilter();
        var filter = ApiFilter.Default.Describe("2.1");
        var dependentTypes = StackOverflow.Api.V2.Helpers.FilterableAttribute.GetDependentFilterableTypes(typeof(Answer)).Keys.Union(new[] { typeof(ApiResult<>) }).Select(s => s.GetApiName()).ToList();
    }
    <script type="text/javascript">
        var parameters = @param.ToJSON();
        var method = "/2.1/answers";
        var filterName = "@filterName";
        var filter = @filter.ToJSON();
        var dependentTypes = @dependentTypes.ToJSON();
    </script>
}

Our API is very regular, so all the documentation views look very similar.

This system is "new" (I guess years old now) to v2.0. In v1.0 we did try some automatic documentation generation using in source comments but it turned into a maintenance nightmare, and was kind of difficult to make work with more interesting methods.

share|improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .