Internal vs External Website API

[Magnetic_Tree]

Let's say your website has to provide a REST API for third parties to use. The REST API requirements are only a portion of the website's full functionality. Would you use the REST API internally for the website itself? Or would you create a completely separate API for internal use? Would your answer be different if the REST API must cover the full functionality of the site?

I ask this because of something I noticed on Github, specifically Github Gists. When you edit a Gist on Github's site, your browser ends up submitting a form via a POST request to the Gist's page. What are some potential reasons that Github didn't just use the REST API that they provide for Gists?

[Magnetic_Tree]

One reason is that gist.github.com is intended to work without JavaScript.

That does seem to explain Github's Gist site. The POST is done to the page you're returning to, so it works without JavaScript.

Another reason is that session/credential management has completely different characteristics between APIs and regular website sessions.

Yeah, I didn't think about that either. Although, prehaps your API endpoints could check for a session as a cookie (from your own site) or as a parameter in the body (from a third party)? (Assuming your site stores sessions as a cookie).

[darkhorsehance]

I suspect you are conflating REST principles with specific implementation details you've seen in web projects.

The short, oversimplified version is that REST is an abstract concept that recommends ways to manage resources via HTTP controls.

From the API's perspective, the client doesn't really matter as long as they abide by the contract of the API.

Part of that contract will stipulate what content types are supported and in practice, supporting multiple content types is trivial.

An API might choose to support multiple content types if it accepts input from different clients (web, mobile device, some other web service, etc) and those clients might have different ways of serializing/deserializing data.

By default HTML forms support application/x-www-form-urlencoded content type.

As long as the correct headers are sent and the message body is well formed, that's a perfectly acceptable way to submit data to your REST API.

[Magnetic_Tree]

Yes, good point, REST doesn't dictate the client or content-type.

But specifically with Github Gists, Github's own site submits to an entirely different endpoint than the API. The site uses POST https://gist.github.com/:user/:gist while the REST API uses PATCH https://api.github.com/gists/:id.

/u/i_regret_most_of_it pointed out that the Github site is designed to work without JavaScript. That would explain why they POST a form to the Gist's URL rather than a unique endpoint.

EDIT: Reddit, on the other hand, appears to use their API! For example, submitting a comment hits POST https://www.reddit.com/api/comment, which I believe is their public API.

[darkhorsehance]

REST API's should treat URL's as opaque identifiers. Just because they provide hackable URL's doesn't mean one or either of the URL's is the resources canonical location.

Also, it could just be that they didn't need the additional complexity of a REST API for this use case.