Review REST requirements for input

[jlouvel]

From this section: http://roy.gbiv.com/pubs/dissertation/web_arch_domain.htm

• Low Entry-barrier
• Extensibility
• Distributed Hypermedia
• Internet-scale
• • Anarchic Scalability
• • Independent Deployment

[mamund]

I question whether the list two (Dist. Hypermedia & Internet Scale) are required for "The Web API" style. This is esp. true if this style is to be applied within an enterprise arch model. In those cases, we only need "Enterprise Scale"

Hypermedia is helpful when release co-ordination is very low (e.g. non-existent on the WWW). However (again, esp. in enterprises) this is not often the case.

Extensibily can be achieved through configuration and portability (esp. of code) w/o the need for hypermedia.

[jlouvel]

The Extensibility requirement can lead into versioned web APIs.

The Dist. Hypermedia requirement should very likely be removed for the Web API style. Even though URIs (relative or absolute) should be used to reference related resources.

The Internet Scale requirement should be refocused. In this blog post, I use the "Application Scale" wording instead. For sure, it should aim at cross-organization/cross-enterprise deployments where web API consumer are not part of the same organization that provides the API. This wouldn't prevent intra-enterprise scenarii like for intranet web sites.

[mamund]

Extensibility does not require versioning. Extending is the least-disruptive way to mod existing APIs. Extensibility can also be handled via portable code and configurability (see my comment earlier). And, are you sure you want to make extensibility a requirement? that's a high bar.

hypermedia is a technique for supporting extensibility. It's not a system property. Are you sure you want to make this a requirement? FWIW, fielding lists is as a constraint.

[jlouvel]

If I adapt the extensibility requirement from REST to the Web API style, I get this:

"While simplicity makes it possible to deploy an initial Web API, extensibility allows us to avoid getting stuck forever with the limitations of what was deployed. Even if it were possible to build a Web API that perfectly matches the requirements of its users, those requirements will change over time just as society changes over time. A Web API intending to be as long-lived as the Web must be prepared for change."

I don't mean anything else than that. Obviously, explicit versionning is a common way to handle this aspect but definitely not the only one you can think of indeed. The style itself shouldn't indeed force a specific way to fulfill this requirement.

BTW, I'm not sure I understood well the final paragraph of your previous comment.

[mamund]

i think we're in agreement here on the general issue. my last para was meant to point out that, like versioning, hypermedia is simply a method for handling change over time. just as i am wary of making versioning a requirement, i am wary of making hypermedia a requirement, too.

i know that the Web has dist. hypermedia as a requirement. i am asking if that is also something you want to require of Web APIs. for example, is it true that all APIs (even ones within an enterprise) are required to use Dist. Hypermedia? it is worth noting that most enterprise implementations do not use hypermedia at this time.

[jlouvel]

I agree that hypermedia shouldn't be a requirement for the Web API style.

This GitHub issue/ticket is only about considering REST requirements and see if they match (or not) with the Web API requirements. That was probably confusing.

[mamund]

ok, i'm cool w/ this.

thanks.

[jlouvel]

Regarding the Low-barrier for entry, we should aim at the simplicity of the web. Being able to use a web API without having to write a program, using a simple/raw HTTP client.

Suggested by Jean-Paul Figer.