I am currently developing a very simple web service and thought I could write an API for that so when I decide to expand it on new platforms I would only have to code the parser application. That said, the API isn't meant for other developers but me, but I won't restrict access to it so anyone can build on that.
Then I thought I could even run the website itself through this API for various reasons like lower bandwidth consumption (HTML generated in browser) and client-side caching. Being AJAX heavy seemed like an even bigger reason to.
The layout looks like this:
Server (database, programming logic)
|
API (handles user reads/writes)
|
Client application (the website, browser extensions, desktop app, mobile apps)
|
Client cache (further reduces server reads)
After the introduction here are my questions:
Is this good use of API
Is it a good idea to run the whole website through the API
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
EDIT
Additional questions:
Any alternative approaches I haven't considered
What are some potential issues I haven't accounted for that may arise using this approach
First things first.
Asking if a design (or in fact anything) is "good" depends on how you define "goodness". Typical criteria are performance, maintainability, scalability, testability, reusability etc. It would help if you could add some of that context.
Having said that...
Is this good use of API
It's usually a good idea to separate out your business logic from your presentation logic and your data persistence logic. Your design does that, and therefore I'd be happy to call it "good". You might look at a formal design pattern to do this - Model View Controller is probably the current default, esp. for web applications.
Is it a good idea to run the whole website through the API
Well, that depends on the application. It's totally possible to write an application entirely in Javascript/Ajax, but there are browser compatibility issues (esp. for older browsers), and you have to build support for things users commonly expect from web applications, like deep links and search engine friendliness. If you have a well-factored API, you can do some of the page generation on the server, if that makes it easier.
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
Tricky one - with this kind of app, you have to distinguish between authenticating the user, and authenticating the application. For the former, OpenID or OAuth are probably the dominant solutions; for the latter, have a look at how Google requires you to sign up to use their Maps API.
In most web applications, HTTPS is not used for authentication (proving the current user is who they say they are), but for encryption. The two are related, but by no means equivalent...
Any alternative approaches I haven't considered
Maybe this fits more under question 5 - but in my experience, API design is a rather esoteric skill - it's hard for an API designer to be able to predict exactly what the client of the API is going to need. I would seriously consider writing the application without an API for your first client platform, and factor out the API later - that way, you build only what you need in the first release.
What are some potential issues I haven't accounted for that may arise using this approach
Versioning is a big deal with APIs - once you've created an interface, you can almost never change it, especially with multiple clients that you don't control. I'd build versioning in as a first class concept - with RESTful APIs, you can do this as part of the URL.
Is this good use of API
Depends on what you will do with that application.
Is it a good idea to run the whole website through the API
no, so your site will be accessible only through your application. this way This implementation prevents compatibility with other browsers
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
You can use omniauth
Any alternative approaches I haven't considered
create both frontends, one in your application and other in common browsers
What are some potential issues I haven't accounted for that may arise using this approach
I don't now your idea, but I can't see major danger.
Related
I'm wondering about additional complexities involved in integrating with Auth0 vs plenty of available code for password complexity rules, UI etc. including using snowflake starter app, for authentication/user creation with open source parse server.
I am sure plenty of people have thought about this and was wondering what the consensus is? Requirement to keep profile/email in sync, relying on 3rd party, inability to customize view and I am sure many other issues.
At first I thought this is great, I would not need to worry about a lot of things, yet there are a lot of other things to worry about and not being able to customize.
What are the most convincing "PRO" answers?
Disclosure: I'm an Auth0 engineer.
TL;DR: I can talk about the pros and cons, but the definitive answer needs to be provided by you.
A bit about Auth0
Auth0 supports the authentication protocols in most widespread use (OAuth2/OIDC, SAML and WS-Federation) so integration into custom software that speaks or can be made to speak by available libraries is relatively easy and friction free. Sidenote, Parse Server does seem to support integration with OAuth compliant identity providers.
It can be used as a standalone identity provider where your users register and authenticate with username/password credentials specific to your application, but it can also integrate with a lot of downstream identity providers like for example Google, GitHub and Twitter. This makes it really easy to enable different methods of authenticating users just by configuration instead of having to directly talk to each individual provider and have to deal with their implementation discrepancies.
Finally, it provides enough extensibility points for you to still have significant degree of control on the authentication experience, for example:
Rules (JS code) allow you to customize the authentication process
Customization of Auth0 provided authentication user interface allows you to still have your own branding
Customization of Lock allows you to have a custom authentication experience integrated in your own app really quick and with very little effort
Of course, no matter how many extension points there's always some stuff that you will not be able to control. This can be seen as bad, but sometimes it's actually a good thing. Depends on the perspective and your specific requirements.
Comparison - Roll your own (RYO) vs Third-party service
On one side you'll have:
cost of acquisition of the service
cost of integration of the service with your product
On the other side you'll have:
cost of implementing the features you need
cost of ownership of those features
cost of integration of the new features in your product
In both cases you'll need some integration work in order to make all the parts fit no matter who created the parts. You could argue that if you are the author of everything it will be easier to fit a square peg in a round hole so lets say RYO wins by a small margin on that point.
It then all comes to comparing cost of acquisition versus the cost of implementation and ownership. I can't answer that one, but the cost of acquisition is generally easy to calculate while the cost of implementing software is very hard to predict; on top of that owning a custom authentication solution also has a heavy toll... you know what they say, no one ever got fired by buying IBM. I won't go that further, but it's safe to say it's easier to find yourself in a pickle if you roll your own security. :)
Conclusions
Go through the Auth0 trial, play with it and see what it has to offer and how that matches your requirements.
If you find something you're not able to accomplish leave a question here tagged auth0 or on Auth0 Forums.
I'm in the middle of writing my first web app. Just wondering how the conventions are when it comes to REST API designs. Is it better to have it reflect my server side architecture or whatever seems to be easier to reason about?
I'm thinking of either doing:
/serviceProvider/product
or
/product/serviceProvider
My server side architecture are all separated into modules organized by service providers, however they all expose a product query API.
APIs ideally should be designed to make most sense for its consumer. There isn't really a good reason to reflect your "server architecture" at all. In fact, it's what's usually called a leaky abstraction or a leaky API and is considered bad practice, mainly because your application structure may change and then you have these possible scenarios:
you need to change your API, which is a non-trivial task when it's already being used by someone;
your API stops being reflective of your application structure which leads to inconsistencies;
exposing your application structure or database schema to the world may have security implications.
With these things in mind, you might as well design the API with focus on ease of use in the first place. The consumer of your API doesn't need to know or care about your application architecture.
I believe that keeping on the same architecture is important because you're forced to offer simple API and it will enforce you a simplified architecture on the server side.
That said, of course that you don't want to expose any server side method or even every server side property of the returned objects.
In Kaltura we also believe in flat (not nested) paths to simplify the API.
For more guidelines, see my blog: http://restafar.com/create-new-rest-server/
Suppose you are developing a platform which has a web-based interface for its users and APIs for third-party developers. Something similar to Salesforce (or even Facebook).
Salesforce and Facebook, both platforms have normal web-based interface for its users and APIs for third party developers.
Ideally any API internally calls the same function which is being used by the web-based interface. For e.g. "Create a Project" button and "CreateProject" API calls the same "createProject()" function internally. So you can maintain the same version for both as in most cases they are tightly integrated.
Now sometimes you add a feature which makes you increment the minor version of the web-based interface but since you are not implementing that feature in API, API version should remain as is.
How do you handle such cases? Should you maintain separate versions of your web-based interface and APIs for your platform?
It Depends. Because It is difficult to offer a conclusive answer to this question. But I would share some ideas and drill-down some scenarios to help at best.
I would suggest there should be two versions of the api. internal apis and public apis. At a caller's end, they would be two physically distinct apis/end-points so that the security policies and a of lot of other things can be done without exposing much information as well as without relaying any responsibility on code to handle the distinction policy based on who's calling from where as that may quite easilyfail.
It is ok if both versions of the apis consolidate down the line to some extent without involving any security risk but a separate team of expert engineers can design this consolidation to be seamless yet safe. It's a trade-off of between code-reuse and everything else. This is very subjective and can turn into endless discussion. But the software evolves very well as result of this design process if it is agile and iterative.
The apis should be externalizable and inter operable. If the project is very large, then different teams working on separate parts of the project will interact with each other's work using internal apis only. No hanky-panky. No direct data access. Only apis.
This approach will help you create awareness of what's being done in the project across all teams if the apis are discoverable which I personally believe is a very good thing for collaborative team work. In fact it also helps in re-usability. Testing becomes unified and automated. Every team will become responsible for their own work and hence it should be easy to address accountability.
There's more stuff that can go in here but I think this is sufficient at a high level.
IF allowed, I would also read this question as
"Should you have purely service oriented architecture or not ?"
And my answer would be, **It Depends.**Because It is difficult to offer a conclusive answer to this...
Do not publish core function directly via API, instead create all API functions as proxy functions and all changes in core functions will be handled in proxy functions.
Change public api version if there is change in API input/output.
This way you could achieve code re-usability and it does not increase public API version frequently.
Edit:
If you are talking about software version number. My answer is Yes.
I'm about to start planning an internal project management tool for my company. One thing that has always led me wondering is APIs.
Would it be seen as bad practice / too inefficient to create a API first and build the actual site using those API calls rather than implement it twice?
Let me know your thoughts!
I completely agree that developing an API will give you a decoupled architecture, and I recommend that.
However, I feel you should be warned that developing the API first increases your risk of developing the wrong API (PM, by the way, is largely about reducing project risk). You will also be tempted to gold-plate your API-- program features that may go unused, which wastes time. Developing the API in conjunction with the application guarantees that it correctly serves the actual application's or applications' needs. Unless you are confident in the accuracy of and your understanding of the requirements, I suggest programming the API one feature at a time with the application.
For example, as you develop the application and discover the precise point at which you need to make an API call, create an interface (depending on the technology) that looks exactly like what you need. You can stub that interface to get the app to run, which is a great tool for checking that the app is still on track with user expectations. ("You want it to work like this, right?") Later, you can implement that interface. If by chance requirements suffer alteration, you won't have spent time building now obsolete infrastructure.
We are developing a middleware SDK, both in C++ and Java to be used as a library/DLL by, for example, game developers, animation software developers, Avatar developers to enhance their products.
Having created a typical API using specific calls for specific functions I am considering simplifying the API by using a REST type API (GET, PUT, POST, DELETE) or CRUD type (CREATE, READ, UPDATE, DELETE) interface.
This would work in a similar way to a client-server type REST API where there are only 4 possible API calls but these can take flexible parameters.
This seems to have the benefit of making the API stable in that new calls are not being added and old calls are not being removed. So a consumer of this API need not worry about having to recompile and change their code to suit any updates to our middleware.
The overhead is that there is an extra layer of redirection in the middleware controller to route API calls and the developer needs to know what parameters are available for each REST call (supplied of course).
I have not so far seen this system used outside of web type client server applications so my question is this: Is this a feasible idea?
I am thinking in terms of its efficiency as well as if for example a game developer would find it easy to use.
Yes, this is a feasible idea. But I'm not sure the benefits would justify the costs. REST is best applied to a networked application scenario, oriented around requests and responses. While there are definite learning curve advantages to a uniform interface, those advantages can be present in almost any well-designed API which provides reasonably abstract procedures.
You also expressed concern for whether a game developer would find a RESTful API easy to use. I'd be dubious. I've implemented many RESTful web services, and helped many developers get up to speed both building them and using them, and the conceptual leap required to grasp REST can be substantial for someone who has been steeped in procedural APIs for years. I'd think that game developers in particular would be very strongly connected to procedural APIs, to the point that attempting to adopt a different paradigm, whatever its benefits, might prove extremely difficult.
Remember that REST is not specific to HTTP, and does not rely on just the 4 HTTP verbs. The verbs you have and can use depend on what protocol you're using.