Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
Everybody can be sure of the benefits and the drawbacks of an open API.
But is it a good or a bad practice to publicly document the open API (which requires authentication for its requests)?
By publicly document I mean creating a documentation showing the structure of the body of the request that the API can receive and by giving descriptions for all these fields.
Eg, given an endpoint my-public.url/myendpoint/myresource, with available PUT, POST, DELETE and GET http requests there's a static page my-public.url/document/myendpointwhich shows all the acceptable http requests along with description for the headers and the body of the request that are needed in order to perform it.
On the one side, this will help external developers to use the API easily, but on the other hand, if somebody gains access somehow, it would be easy for them to make requests and corrupt the system, since the whole structure of the API is given.
You can look at this from the risk perspective. Providing public documentation for an API presents a risk, for the reason you mentioned, it may help an attacker. On the other hand, security is always a balance, providing documentation helps (or is even necessary for) your users.
Also you shouldn't implement security by obscurity, ie. how things work should be considered known to attackers - but it's true that many times that's not the case in reality.
As providing public documentation is a risk, you then have to treat it somehow. You can do several things with risk, for example you can accept it (~do nothing), eliminate it (~not provide documentation in this case), or mitigate it.
Mitigating this risk would mean additional things you do to make an exploit less likely, or to decrease the impact. Likelihood can be reduced by for example stronger controls around how you develop your software, adding automated testing around authentication and authorization features, adding static code analyzers to the mix and so on. Impact can be reduced by good architecture that separates logical layers, intrusion detection/prevention systems, or even going for single tenant instead of multi-tenant.
In the end it all comes down to what risk you want to accept, and that entirely depends on you. With proper controls, it is ok to provide public docs - how else could you expect users to be able to use your api? The question is what are "proper" controls, and that depends on your risk appetite.
Risk in your application's APIs is not at all increased because of publicly documenting it.
Here are some reasons which I get in mind when thinking of this,
If you are having a browser based client, anyone with a bit of knowledge to inspect the browser developer tools' NETWORK tab can find your API details.
In case if there is any mobile client which uses your API, the request information can be easily viewed using applications like WireShark. The most famous API tester application POSTMAN also supports such a functionality.
With the help of the above tools, it's more likely for anyone can know about your API details.
Advantages of public documentation
API consumers can just visit your public API documentation which clearly saves a lot of man-time in API developer-consumer communication. (Version based API (and documentation) will be very helpful in time of changes in existing ones)
Creating API demo/test kits like Postman Collections will help the API consumers to test and use the APIs easily.
Here are some points which you can note to reduce the risks in your application.
Authentication - Login credentials / Access token / API Keys
Authorization - Access check for any resource which is being accessed / modified.
API Rate limiting - To avoid a DOS attack.
Related
after reading all the threads on stackoverflow and other platforms, I still wasn't able to find an answer, which satisfies me.
The task:
I want to create a single page application (SPA) which receives data from a REST API. In this SPA, NO authentication should be used. It's a public site.
But the REST API should only be accessible from people who loaded the SPA from my webserver.
I assume this is only solvable with something on server side like sessions, cookies etc. - otherwise I'm open for your suggestions, solutions etc.
Thx in advance!
There's no reasonably easy way to do this. You can easily prevent other domains (in browsers) from accessing a an API on your domain (via CORS), but it's significantly harder to prevent scripts from doing this.
The issue lies in 'how do you detect legit browser traffic from a script'. It turns out that this is not easy. You could try to detect 'unusual behavior' as much as possible (for example a large amount of requests in a short time), but this doesn't stop clients that are slower.
Ultimately if people want your data, they will find some way around whatever restrictions you come up with. You should reevaluate this and use one of the following options:
Don't do an SPA and API. Although one could wonder, if the data exists in HTML it can still be crawled.
Add authentication. But obviously this won't help you in any way if anyone can authenticate.
Re-evaluate why you have this restriction. What are you worried about? If you're worried about people taking your data and using it elsewhere, how does only showing it in a browser from 1 domain help with that? If you're worried about copyright theft, why not use a legal approach to this?
I've seen a lot of these types of questions, but in my opinion I haven't yet seen one that has a legitimate good reason to want this. But, maybe you're the first.
I believe I answered my question myself on a comment 30 minutes ago... I think with captcha I'm able to secure the REST API against unwanted access to my REST API
In my years specifying and designing REST APIs, I'm increasingly finding that its very similar to designing a website where the user's journey and the actions and links are story-boarded and critical to the UX.
With my API designs currently, I return links in items and at the bottom of resources. They perform actions, mutate state or bring back other resources.
But its as if each link opens in a new tab; the client explores down a new route and their next options may narrow as they go.
If this were a website, it wouldn't necessarily be a good design. The user would have to either open links in new tabs or back-up the stack all the time to get things done.
Good sites are forward only, or indeed have a way to indicate a branch off the main flow, i.e. links automatically opening in new windows (via anchor tag target).
So should a good REST API be designed as if the client discards the current resource and advances to the next and is always advancing forward?
Or do we assume the client is building a map as it goes, like um a Roomba exploring our living room?
The thing with the map concept is that the knowledge that one should return to a previous resource, of the many it might know about, is in a sentient human, a guess. Computers are incapable of guessing and so its need programming, and this implies out-of-band static documentation and breaks REST.
In my years specifying and designing REST APIs, I'm increasingly finding that its very similar to designing a website
Yes - a good REST API looks a lot like a machine readable web site.
So should a good REST API be designed as if the client discards the current resource and advances to the next and is always advancing forward?
Sort of - the client is permitted to cache representations; so if you present a link, the client may "follow" the link to the cached representation rather than using the server.
That also means that the client may, at its discretion, "hit the back button" to go off and do something else (for example, if the link that it was hoping to find isn't present, it might try to achieve its goal another way). This is part of the motivation for the "stateless" constraint; the server doesn't have to pretend to know the client's currently displayed page to interpret a message.
Computers are incapable of guessing and so its need programming, and this implies out-of-band static documentation and breaks REST.
Fielding, writing in 2008
Of course the client has prior knowledge. Every protocol, every media type definition, every URI scheme, and every link relationship type constitutes prior knowledge that the client must know (or learn) in order to make use of that knowledge. REST doesn’t eliminate the need for a clue. What REST does is concentrate that need for prior knowledge into readily standardizable forms. That is the essential distinction between data-oriented and control-oriented integration.
I found this nugget in Fielding's original work.
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations. Not surprisingly, this exactly matches the user interface of a hypermedia browser. However, the style does not assume that all applications are browsers. In fact, the application details are hidden from the server by the generic connector interface, and thus a user agent could equally be an automated robot performing information retrieval for an indexing service, a personal agent looking for data that matches certain criteria, or a maintenance spider busy patrolling the information for broken references or modified content [39].
It reads like a great REST application would be built to be forward only, like a great website should be simple to use even without a back button, including advancing to a previously-seen representation (home and search links always available).
Interestingly we tend to really think about user journeys in web design, and the term journey is a common part of our developer language, but in API design this hasn't yet permeated.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I'm tasked with investigating for our firm a full-stack solution where we'll be using a NoSQL database backend. It'll most likely be fed from a data warehouse and/or operational data store of some type in near-realtime (hopefully :). It will be used mainly by our mobile and web applications via REST.
A few requirements/assumptions:
It will be read-only (in the near term) and consumed by clients in REST format
It has to be scalable
Fast response time
Enterprise support - or if lacking actual support, something industry proven if open-source (basically management wants to hold
someone accountable if something in the stack fails)
Minimal client data transformations - i.e: data should be stored in as close to ready-to-use format as possible
Service API Management of some sort will most likely be needed (eg: 3scale)
Services will be used internally, but solution shouldn't prevent us from exposing them externally as a longterm goal
Micro-services are preferable (provided sufficient API management is in place)
We have in-house expertise in Java and Grails for our mobile/portal solutions
Some of the options I was tossing around were:
CouchDB: inherently returns REST - no need for translation layer - as
long as clients speak REST, we're all good
MongoDB: need a REST layer in between client and DB - haven't found a widely used one based on my investigation (the ones on Mongo's site all seem in their infancy - i.e: RestHeart)
Some questions I have:
Do I need an appserver? Or any layer in between the client and DB
for performance/caching reasons? I was thinking a reverse-proxy like
nginx would be a good idea for this?
Why not use CouchDB in this solution if it supports REST out of the box?
I'm struggling with deciding between which NoSQL DB to use, whether or not I need a REST translation layer, appserver, etc. I've read the pros and cons of each and mostly they say go Mongo - but for what I'm trying to do the lack of a mature REST layer is concerning.
I'm just looking for some ideas, tips, lessons learned that anyone out there would be willing to share.
Thanks!
The problem with exposing the database directly to the client is that most databases do not support permission control which is as fine-grained as you want it to be. You often can not allow a client to view and edit its own data while also forbidding it from viewing and editing any data of other users or even worse from the server itself. At least not when you still want a sane database schema.
You will also often find yourself in the situation that you have a document with several fields of which only some are supposed to be under the control of the user and others are not. I can, for example, edit the content of this answer, but I can not edit the time it was posted, the name it was posted under or its voting score. So far I have never seen a database system which can handle permission for individual fields (when anyone has: feel free to post in the comments).
You might think about trying to handle this on the client and just don't offer any user interface for editing said fields. But that will only work in a trusted environment. When you have untrusted users, they could create a clone of your client-sided application which does expose this functionality. There is no way for you to tell the difference between the genuine client and a clone, especially not when you don't have a smart application server (and even then it is practically impossible).
For that reason it is almost always required to have an application server between clients and database which handles authentication and permission management of the clients and only forwards those requests to the persistence layer which are permitted.
I totally agree with the answer from #Philipp. In the case of using CouchDB you will minimum want to use a proxy server in front to enable SSL.
Almost all of your requirements can be fulfilled by CouchDB. Especially the upcoming v2 will give you the "datacenter-needs".
But it's simply very complex to answer what should be the right tool for you purpose. If you get some business model requirements on top like lets say: throttling - then you will definitely need an application server middleware like http://mcavage.me/node-restify/
Maybe it's a good idea to spend some money to professionals like
http://www.neighbourhood.ie/couchdb-support/ ? (I'm not involved)
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm designing a REST-like API over Http.
I need the API Clients (apps, not browsers) to follow the links (HATEOAS), not to build them.
Also, I'll still use readable URLs for some reasons that can be disagreed.
However, if pretty ways to document url templates exist (like these ones), I don't think it is the right way as it could clearly tempt and legitimate developers to build urls themselves.
So, How to document an API in a way that respects HATEOAS ?
We often find Discoverability associated to HATEOAS.. To be honest, I don't think this is enough in real life : where business concepts are multiple, subtle to understand and client developers are not your teammates..
Meaningful names are clearly not enough.
Developers need to make their Client apps ..
Navigate into the API from the entry url to the relevant documents
Build valid requests (parameters and bodies) and interpret responses with no ambiguity on the semantics.
So, How to document this ?
Are there existing tools that generate documentation this way ?
Would a "Glossary" be enough to fill-in the gap between discoverability and unambiguous interpretation ?
Maybe the html representation of the API (Accept:text/html) could return human readable documentation...
.. any other idea or experience on this ?
Related concepts :
Design with Intent, Versioning, Level 3 API
First of all, there's nothing wrong with readable URIs and with users being able to easily explore your API by building URIs by hand. As long as they are not using that to drive the actual API usage, that's not a problem at all, and even encouraged by Roy Fielding himself. Disagreement on that on the basis that URIs must be opaque is a myth. Quoting Fielding himself on that matter:
Maybe I am missing something, but since several people have said that REST implies opaqueness in the URI, my guess is that a legend has somehow begun and I need to put it to rest (no pun intended).
REST does not require that a URI be opaque. The only place where the word opaque occurs in my dissertation is where I complain about the opaqueness of cookies. In fact, RESTful applications are, at all times,
encouraged to use human-meaningful, hierarchical identifiers in order to maximize the serendipitous use of the information beyond what is anticipated by the original application.
It is still necessary for the server to construct the URIs and for the client to initially discover those URIs via hypertext responses, either in the normal course of creating the resource or by some form of query
that results in a hypertext list. However, once that list is provided, people can and do anticipate the names of other/future resources in that name space, just as I would often directly type URIs into the
location bar rather than go through some poorly designed interactive multi-page interface for stock charts.
http://osdir.com/ml/web.services.rest/2003-01/msg00074.html
If you need your client developers to follow the hyperlinks and not build URIs by hand, from my experience I think the best way to do that is to promote it as a cultural change in your work environment. In my case I had a supportive manager, so it was much easier. You should warn them that the URI namespace is under control of the server and the URIs may change anytime. If their clients break because they failed to comply, it's not your responsibility. It also helps a lot to have some sort of workshop or presentation to explain how HATEOAS works and the benefits for everyone. I noticed how a lot of street-REST developers think it's superfluous, until they actually get it.
Now, to address your main question, you shouldn't document the API, you should focus your documentation efforts on your media-type. Quoting Fielding again:
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
That means, you should have custom media-types for your representations, and instead of documenting API endpoints or URIs, you should document those media-types and the operations for the links available in them. For instance, let's say you have an API for a Q&A site like StackOverflow. Instead of having an API documentation telling them that they should POST to the rel:answers link in the representation of a question in order to answer it with their current user, your questions should have a media-type of application/vnd.yourcompany.question+xml and on the documentation for that media-type you say that a POST to a rel:answers http link will answer the question.
I don't know of any existing tools for this, but from my experience, any tool that can be used to generate documentation from abstract models can be used for this.
I don't know how your ecosystem of APIs is, but what works for me is to have a generic documentation with a gentle introduction to REST, addressing some of the misconceptions, and detailed general usage to your patterns, that should apply to any API. After that, each individual server should have its own documentation, focused on the media-type.
I don't like the idea of returning documentation in the text/html representation, because that's supposed to represent the resource itself, but I love the idea of having a rel:doc link pointing to your HTML documentation for that media-type.
I'm admittedly unsure whether this post falls within the scope of acceptable SO questions. If not, please advise whether I might be able to adjust it to fit or if perhaps there might be a more appropriate site for it.
I'm a WinForms guy, but I've got a new project where I'm going to be making web service calls for a Point of Sale system. I've read about how CRUD operations are handled in RESTful environments where GET/PUT/POST/etc represent their respective CRUD counterpart. However I've just started working on a project where I need to submit my requirements to a developer who'll be developing a web api for me to use but he tells me that this isn't how the big boys do it.
Instead of making web requests to create a transaction followed by requests to add items to the transaction in the object based approach I'm accustomed to, I will instead use a service based approach to just make a 'prepare' checkout call in order to see the subtotal, tax, total, etc. for the transaction with the items I currently have on it. Then when I'm ready to actually process the transaction I'll make a call to 'complete' checkout.
I quoted a couple words above because I'm curious whether these are common terms that everyone uses or just ones that he happened to choose to explain the process to me. And my question is, where might I go to get up to speed on the way the 'big boys' like Google and Amazon design their APIs? I'm not the one implementing the API, but there seems to be a little bit of an impedance mismatch in regard to how I'm trying to communicate what I need and the way the developer is expecting to hear my requirements.
Not sure wrt the specifics of your application though your general understanding seems ik. There are always corner cases that test the born though.
I would heed that you listen to your dev team on how things should be imolemented and just provide the "what's" (requirements). They should be trusted to know best practice and your company's own interpretation and standards (right or wrong). If they don't give you your requirement (ease-of-use or can't be easily reusable with expanded requirements) then you can review why with an architect or dev mgr.
However, if you are interested and want to debate and perhaps understand, check out Atlassian's best practice here: https://developer.atlassian.com/plugins/servlet/mobile#content/view/4915226.
FYI: Atlassian make really leading dev tools in use in v.large companies. Note also that this best-practices is as a part of refactoring meaning they've been through the mill and know what worked and what hasn't).
FYI2 (edit): Reading between the lines of your question, I think your dev is basically instructing you specifically on how transactions are managed within ReST. That is, you don't typically begin, add, end. Instead, everything that is transactional is rolled within a transaction wrapper and POSTed to the server as a single transaction.