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.
Related
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 1 year ago.
Improve this question
So my friend needed to develop new API for creating item, so he developed:
POST /new/item
POST /item/new
PUT /new/item
PUT /item/new
All of them call the same underlying function and accept same parameters.
I recommended that he uses only 1 instead of 4, but he says that there is no down side and he's giving the option for anyone who wants to integrate with this API to use whatever personal variation they like.
Question: Is it really that there is no down side by doing this in the long run?
There is no downside in regards to functionality, but an API with redundant endpoints will probably be
Harder to maintain. If a change to the endpoint is needed, it may have to be made four times depending on the setup
Confusing for users of the API. While I imagine it's the intention behind this setup to catch typos in URLs and still allow the API to work, documentation on the endpoints will be bloated and harder to read
Lacking consistent naming. Ideally, there is a logic behind how endpoints are named, allowing users to infer what an endpoint does by its name and verb (GET, POST etc). Having multiple naming schemes makes it harder to understand the naming.
There is no meaningful upside to making redundant endpoints, and I would recommended to use POST /item for creating a new item.
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 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 have a setup where it is possible to get some resource using standard REST and this is easy documented in swagger. The same resource is pushed to clients using websockets when it has changed, so clients does not have to do a pull on an interval basis.
But how can I document this in swagger? Is it even possible? If not, what other tool do you recommend for documenting both the REST api and the websocket part?
OpenAPI 3 (aka Swagger 3) has an upgrade in the response formats where they added the concept of callbacks, which allow you to define a webhook. Take a look at this part of the documentation: response format.
In Swagger 2 what I use to do is to implement an API method that implements exactly the same I expect from a callback and I just reference it in the original method that waits the callback. So any consumer can at least see the format of message that I'm expecting from them, using the Swagger specification.
It is difficult today to find a clear answer on "How to document apis using async communication". It is not only about websocket but also Server Send events and others....
Today, for Rest specification, there are many famous specifications and the top 3 is:
- Swagger
- RAML
- API Blue Print
They are a lot of issue/discussion about a way to document apis using websocket,...
But Swagger is standardizing api specification with the help of the community. It's named OpenApi.
The version 3 of the OpenAPI specifications introduce a way to document webhook/callback.
Another good specification is asyncapi.com which is going deeper and respect the readeable openApi specs.
The Swagger spec defines a limited set of operations, which you may define for a particular path object in your schema. That being said, you are free to step outside of the spec if you only care about documenting your API for human use. Take a look at WIX docs for example. It uses a custom HOOK definition to document its webhook API and it doesn't pretend to be a valid Swagger spec, which may be just what you need in your case.
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.
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
Thinking about service orientation, our team are involved on new application designs. We consist in a group of 4 developers
and a manager (that knows something about programming and distributed systems). Each one, having own opinion on service design.
It consists in a distributed system: a user interface (web app) accessing the services in a dedicated server (inside the firewall), to obtain the business logic operations.
So we got 2 main approachs that I list above :
Modular services
Having many modules, each one consisting of a service (WCF).
Example: namespaces SystemX.DebtService, SystemX.CreditService, SystemX.SimulatorService
Unique service
All the business logic is centralized in a unique service.
Example: SystemX.OperationService. The web app calls the same service for all operations.
In your opinion, whats the best? Or having another approach is better for this scenario?
A web service is an interface. The invoker doesn't care how a service works, it just needs to know what arguments to supply and what outcomes to expect. So a multitude of simple, discrete servcies is probably better.
Behind their interfaces they can all join up in one great big bundle of business logic. Who cares?
In practice, teach of hese services will share some elements of SystemX functionality and will have some elements which it alone uses. Some may combine elements of SystemX and SystemY. If SystemX and SystemY are legacy apps it may not be possible to change them, so we have to work with them as they are. In other scenarios it is possible to expose impose modularity on them.