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 5 years ago.
Improve this question
I've been looking for automatic creating the documentation for the REST API of a project I'm working on. First, Hydra (http://www.hydra-cg.com) shows up with an interesting idea for designing Web APIs. Later some colleagues recommend me to use Swagger 2.0 (http://swagger.io) as code generator. Then, I realise that both specifications can solve the same problem of documenting the REST API.
What are the downsides/benefits of using Hydra or Swagger specification?
Thanks!!!
Swagger is well established and supports a wide range of languages and frameworks. It doesn't force you to write the API in a specific style and it should be a better fit if you just want to document an existing API.
Hydra looks like interesting framework to develop REST APIs but has yet to be adopted by any standards organizations and the industry to make it a real standard. It's just an unofficial draft by a W3C community group for now. It also seems very new and provides experimental tools for some languages, which don't seem ready for production. I'm not even sure if you can integrate the framework with an existing API without changing the API significantly.
As stated by inf3erno, Hydra is more focused on the original definition of REST services and generated documentation is just a byproduct. On a first glance it seems to me that they are using principles similar to HATEOAS and try to formalize that technique using vocabularies. I think there is good reason to stay with the more simple modern definition of REST services though and don't make development to complicated by adding HATEOAS or vocabularies.
Hydra is about creating a REST specific vocab, so after it became a standard, every REST API can use that vocab, and it will be possible to write general REST clients, just like browsers are for human users on the web currently. That is real REST. Current so called REST APIs don't fulfill the uniform interface constraint, because they use non-standard solutions. Hydra will solve this problem. It's just an insignificant detail, that it is possible to generate documentation from an API specific vocab if it is described with hydra terms.
A don't know what swagger is, but it appears to be a non-standard solution to the same problem.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 6 years ago.
Improve this question
I wish to know if in the development of an application, the API developed can used by both the client app and the mobile app?
For example, having an API that manges products in Symfony 2. A client app is developed in AngularJs to make the web app complete.
I concern is, is it a best practice to use this same API for the mobile app or to create another set of APIs strictly for the mobile App?
tl;dr; - Yes, you should, but consider drawbacks!
In ideal, you sure can and you should utilise the same REST API for all your clients. This will result in more maintainable system. Angular.js also has a special factory/service called resource that will do all the heavy lifting for you.
However, we don't live in an ideal world and you would face some "side effects". For example, several years ago Twitter decided to do exactly this and their website used to load javascript and then only query the REST API for tweets. This led to perception of "slow" page rendering. Twitter dropped the idea.
So, the quick answer is "Yes, you should", but the real world answer is "Consider advantages and drawbacks, only then, make your own decision".
Yes and actually that's one of the main reason we make REST APIs...
So you don't have to build multiple server backend logic per client applications you make.
I don't know for React.js but Angular does handle it very well :)
Have a look at $http and $resource
https://docs.angularjs.org/api/ng/service/$http#patch
Yes, AngularJS supports PATCH.Look at the documentation over here.
With ReactJS, it depends which library you are using. But, React is just a really small library, so you are totally free to use plain JavaScript to make PATCH work. See here.
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 6 years ago.
Improve this question
I attended a seminar about API basics yesterday and something struck out as odd to me. We covered a basic synopsis of what REST is and what SOAP is and these were defined as architectures of an api.
The way the presenter defined it is that programs have languages and apis have architectures. Is this the proper definition of what an architecture is for an api?
I've looked around on google trying to compare the two terms programming language and architecture and haven't found a clear result.
That statement was almost definitely hand-wavey over-simplification, and was probably only correct within the context of the point he was trying to make.
Architecture is the design and documentation of the high-level functioning of programs and the interaction of those programs.
Programs are implemented in languages, APIs are implemented as programs.
APIs are a documentation of a particular interface to a program, and thus are part of an architecture. APIs are implemented as programs, that themselves have architectures, that fit into a larger system architecture.
I would ignore his statement, it is not helpful to your mental model. Understand what programs are, what languages are, and what architecture is.
REST and SOAP are not even peers. REST is an architectural style, often implemented as HTTP verbs. It is contrasted with RPC style web services, which are often implemented with SOAP. SOAP is a protocol that sits on top of HTTP to implement RPC style web services, it is not an architecture, it is a protocol. REST is not a protocol, it is an architectural element. None of these are a full architecture in and of themselves. SOAP/REST/HTTP/programs/languages all are components in an architecture.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 4 years ago.
Improve this question
APIs like googlemaps API of facebook API are public and can be consumed by anybody. So my question is how do you make REST API private so it can be consumed only by choosen one consumer. For example You make Rest API only for your pwn AngularJS app. Is it common to do this, what is real world approach for this? And in that matter is there any differences between REST API and REST Web Services?
If I were to write a private RESTful API, I probably wouldn't bother to make it RESTful in the first place.
By making a REST API private, you're losing one of this architectural style's primary advantages. Implementing an API like this is difficult but in return you get the ease of scalability and the ability for the consumers of your API to write clients that are not likely to break because of future changes (as long as you follow HATEOAS and use well-defined formats).
If you have the option to control both the service and all of its clients, giving up some of the constraints imposed by a RESTful architecture might actually be a good idea.
You should be fine with a simple API that serves JSON over HTTP as long as you stick to the protocol semantics.
In other words, you could implement a service that fulfils the requirements of a Level 2 API, as described by the Richardson Maturity Model
Because you wouldn't be making full use of the advantages offered by a Level 3 API, not to mention an actually RESTful API, implementing one could just prove an unnecessary effort.
I gave a more comprehensive description of these design considerations in my answer to a programmers.stackexchange question. You can find some useful references in there as well.
You can make API private by requiring some authorization / authentication to use it (simple API keys for example).
REST API vs REST Web Services?
Well, put it this way. REST Web services have REST APIs. Web service is a group of APIs united by purpose.
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 5 years ago.
Improve this question
I'm looking for a nice way to generate documentation for a REST API. It doesn't need to actually connect with the code or anything, but it'd be awesome to be able to write the documentation as text files, point the tool at it, and generate some docs from it.
Anyone out there have any ideas? I know I'm being a bit vague, but, to be honest, I'm not quite sure what I'm looking for here--mainly an easy way to manage documentation.
According to Roy:
"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."
Self-descriptiveness is one of the benefits of REST.
While not REST, I used Sphinx to document an XML-RPC API that consisted of an API reference and a tutorial. Sphinx adds some handy directives to ReStructuredText to get pretty much what you asked for: a collection of ReStructuredText formatted-text files that Sphinx turns into HTML and PDFs, complete with an index and table of contents. Sphinx is easy to use and well-documented; I don't think it would be an exaggeration to say you could get started with it in about ten minutes.
Some RESTful systems are actually able to write their own API. Have a look at RESTx, which does just that: You write your components and then create new web services by sending parameters for those components to the server (either as JSON or via a web form). You then get a URI back for those parameters. Accessing it calls the component with the parameters and you retrieve the results.
At any rate, the components as well as the created RESTful web services get an automatically generated documentation, which is browseable and can be retrieved either in HTML or JSON format.
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 5 years ago.
Improve this question
I work for a insurance company. We have our own development department made-up of almost 150 people plus some providers (outsourcing and custom made apps pretty much). In our company my team have made what we call non-functional logic libraries. That is, software libraries to handle things that are horizontal to all the development teams in our department, e.g. Security, Webservices, Logging, Messaging and so on. Most or these tools are either made from scratch or adaptation of a de-facto standard. For example our logger is an appender based on Log4J that also saves the logging messages into a DB. We also define what libraries to use in the application, for example which framework for webservices to use. We use pretty much JavaEE and Oracle AS in all our organization (with some Websphere Application servers).
Much of these projects have their architecture documented (use cases, UML diagrams, etc) and generally the generated documentation are available.
Now what we have seen is that for users sometimes is difficult to use the the libraries we provide and the are constantly asking question or they simply don't use them.
So we are planning to generate a more friendly documentation for them, so my question is:
What are the best practices or the checklist that software documentation should have?
Something comes to my mind:
API Reference guide
Quick start Tutorial
API Generated Documentation.
Must be searchable
Web Access
What else should it have? Also, based in your experience what is the best way to maintain (keep it up-to-date) and publish this type of documentation?
Keep your documentation in version control too.
Make sure on every page it has a version number so you know where your user has been reading from.
Get a CI server going and push documentation to a LIVE documentation site upon updates.
Do documentation reviews like you would code reviews.
Dog-food it :)
Kindness,
Dan