I'm going to build an API for a web app and I'm interested in what people can suggest as good practices.
I'm already planning to make it versioned (version 1 can only control certain aspects of the system, version 2 could control more, but this may need a change in the way authentication is performed that would be incompatible with version 1), and the authentication will be distinct from the standard username/password people use to log in (if someone does use a malicious tool it won't open them up to full impersonation, just whatever the api allows).
Does anyone have further ideas, or examples of sites with particularly good APIs you have used?
Read the RESTful Web Services book, which give you a good overview of how to use REST in practice, and get to up to speed quickly enough to get started now, with some confidence. This is more useful than just looking at an existing API, because it also discusses design choices and trade-offs.
1) Bake the version number directly into the URL rather than passing it as a parameter, since that gives you complete freedom to change the organization of your API namespace with each version bump.
2) Keep your URL rewriting rules (if any) as simple/lean as possible (but no simpler), while making your URLs as beautiful as possible (but no more).
3) Always look for the best HTTP status code you can find for each response (and don't forget about 202 and 207, for example).
4) Implement fascist parameter validation logic, and informative error messages.
5) Use HTTP request headers where appropriate instead of parameters (like Accept, for example, to allow clients to specify the desired data format of the response).
6) Organize your "nouns" in such a way that the URLs used by different client audiences are separated near the "root" of your URL tree (this makes it easier to enforce different authentication mechanisms for those different audiences if needed, or even map different portions of your URL tree to different servers).
7) If you're serving regular web pages off the same domain as your APIs and use the same authentication credentials, require an X-Requested-With header in your API requests so as to avoid XSRF vulnerabiities.
I would take a look at proven APIs:
YouTube API
Twitter API
There's a lot of argument about whether these APIs are "good" but I think their success is demonstrated, and they're all easy to use.
Use REST.
RESTful web services architecture is easy to implement and uses the strengths and semantics of HTTP for what they were intended. It's resource-oriented, just like the web itself.
Amazon Web Services, Google and many others offer REST APIs to interact with their products.
Use REST.
Read up on standards for APIs, or copy the ideas from one of the popular ones.
Be careful when authenticating users.
Start very very simple.
Build a site that uses your API (even if it's not useful) to check things work. Perhaps you could build a mobile version of the site or something that forces you to use the API in a lot of depth.
Related
(Please let me know if this question belongs to a different stackexchage site)
I have a use case where the clients of my service have to call some APIs exposed in the service. The API specification model being used allows for auto-generation of client bindings for different languages.
I need to provide an enhanced functionality around some of the APIs and that custom code sits around the calls to the API. Instead of expecting every client to write this code on their own, I would like to provide this as a wrapper around the auto-generated client library. I understand that this needs to be done for different languages to be supported (the list if 2-3 in my case).
In general, is this a good choice to make? Are there any other alternatives?
Please let me know if more details are needed.
Generating clients from some kind of API Definition (like OpenAPI) and shipping it with other code is a very common pattern and i've used and created such clients in the past. For the consumers of your API this has some clear advantages: He doesn't have to generate the client (depending on the used technologies is sometimes painful), he benefits from the maintenance done by the provider (and others), and uses the official way to interact with the API.
In such a client there are three main packages which should separated and independent from each other:
The generated client
Code which eases the usage of the generated client
Other Code (i.e. utilities that abstract or simplify common interactions, provide domain logic required on the client side etc)
If these are separated it is very easy for a consumer to pick the pieces he wants to use.
The main disadvantage is that you have to implement and maintain multiple clients for your API. Depending on the size of your API, the supported platforms and environments the clients are used in, this can be a very elaborate task. Also keep in mind that providing a decent client library requires a good understanding of the target platforms and environments. Otherwise your client library might not be accepted by other developers.
In general generated code if often not that "natural" and "nice". For example the generated identifiers might not follow the conventions of the platform or it requires the usage of over complicated constructs like factories to create a simple object. Often the generators can be tweaked, but this adds to the required effort.
All these efforts often add up, so that even big API Providers struggle to provide good client libraries for many platforms.
There are two alternatives:
Only provide a API Definition
Handcraft a client
The first alternative gives the consumer the freedom to choose the way he wants to use your API. But given a good API Definition (which is hard to write), it is relatively easy to do so. In this case it is not possible to provide some additional code to the client. But in general you should aim for dumb clients and avoid clients to perform business logic.
A handcrafted client is best suited if you aim for a limited number of platforms on which you want to provide the best possible experience for the consumers. Further you can implement all kinds of other stuff. But even for a single platform this might be a huge effort.
Ok, so I'm struggling a little bit with trying to get a authentication process in my ASP.NET MVC5 (Web API 2) project. To start, here are some requirements:
I can't use Entity Framework (all access to the DB needs to be done through stored procedures)
Needs to target .NET Framework 4.5.2
I am not using ASP.NET Core
I would like to be able to use Bearer (or similar) tokens for authentication
I would like to invalidate tokens if a user logs out or automatically invalidate them after 24 hours
I would like to pass (and receive) XML when sending requests to the "login" (or "token") endpoint (note that ideally the solution should respect the "Content-Type" and "Accepts" headers, so if I send it JSON it should respond in JSON, and if I send it XML it should respond in XML)
I will not be using external providers (e.g. Google) anytime soon (maybe never)
I would like to use the <Authorize> attributes to help with protecting other endpoints
I am using VB.NET, although answers to this question can be in C# (I can convert them or rewrite them to suit)
I would like to store the tokens in the database so I can record which user is doing what within the API
(note that there are lots of reasons why I can't change the above)
I've tried to do this with Owin (OAuth) but I've found the following issues when comparing this to the requirements:
I can't seem to send the token endpoint any XML
Responses from the authentication endpoints (both successful and unsuccessful) are in JSON
I can't invalidate the tokens when logging out
I am happy to move away from OAuth if that is the best way to go for what I want. I would prefer to use Microsoft built nuget packages (ie no third party solutions) or I'm happy to partially roll my own solution (I would like to leverage as much of in-built or Microsoft built code, including Identity and Claims as possible so I can minimise testing efforts).
I have read numerous StackOverflow questions about this and search heaps on the internet, but most articles stick with OAuth despite the above issues or they rely on EntityFramework. My current solution uses the code from here (pretty much copy/pasted with some custom code in ApplicationOAuthProvider.GrantResourceOwnerCredentials()): https://www.codeproject.com/Articles/1187872/Token-Based-Authentication-for-Web-API-where-Legac
Thanks for the help!
I did some more extensive research and it looks like OAuth is not applicable for my specific situation. Although it seems like a nice authentication method, I really need to invalidate tokens via the DB, and I need the API to always send/receive XML (these are apparently not applicable when using OAuth).
To solve these problems, I have rolled my own token-based solution that creates a hashed token on the client side, so I never send passwords over the wire (which is a little bit nicer) because the token is generated on the client side (note that I am controlling what happens on the client side - these are all in house clients and I am writing the libraries these clients will use). This involved me creating my own filter which inherits System.Web.Http.AuthorizeAttribute.
If anyone stumbles across this question and provides a really good answer, I'm more than happy to mark theirs as accepted.
I am pretty new to stuff related to server and backend services and I want to develop a mobile app with a backend part. I want this backend to serve an ios app, an android app as well as a website.
My concerns today are how does the frontend part communicate with the backend part :
does it work the same way a website works ? (Http request to the server ?)
how does happen the exchange of datas between the frontend and the backend ?
which are the common solutions to my problem ?
is there an efficient way to desing this backend to serve mobile apps as well as a website ?
is parse (https://parse.com/) a good starting point ?
Thanks
Looking at your questions in turn:
does it work the same way a website works ? (Http request to the server ?)
There are many options, but probably the most common, or fashionable, at the moment is to use a RESTFUL interface:
http://en.wikipedia.org/wiki/Representational_state_transfer
Previously, a SOAP based web service might have been the most common choice:
http://en.wikipedia.org/wiki/SOAP
See here for some discussion on why you might use REST rather than the SOAP now:
Why would one use REST instead of SOAP based services?
how does happen the exchange of datas between the frontend and the backend ?
Assuming REST, HTTP is used to transport messages and application data is typically included in XML or JSON forms
which are the common solutions to my problem ?
I think this is covered by the other parts of the question/answer.
is there an efficient way to desing this backend to serve mobile apps as well as a website ?
Thats very dependent on your particular server application, especially its size and architecture. If the server application is broken down into components or parts, and the parts that generate the 'views' or the 'HTML' pages for the web app are distinct and well separated from the 'backend' parts of your server application, AND your application is of a type that the functionality is largely the same whether the end user is using a web site or a mobile and it is just the way the view are generated for the different devices that differs, then an efficient design would be one that keeps as much of the backend common as possible. If the use of the application is very different when used by a mobile client this may not make sense. More generally, an efficient design would keep as much functionality as possible common between the Mobile and Web applications.
It would definitely be worth becoming familiar with the 'Model View Controller' architectural pattern as most of the server side frameworks, as well as many of the Javascript Web client frameworks and even the iOS and (to a lesser extent) Android frameworks use these concepts:
http://en.wikipedia.org/wiki/Model–view–controller
One important considerations whether you need 'push' or notification like functionality on your mobile app. If so you may want to look at some of the common solutions to understand if they meet your needs - probably easiest to start with Apple and Google's offerings to get an understanding, but there are lots of other solutions available also:
https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html
http://developer.android.com/google/gcm/index.html
is parse (https://parse.com/) a good starting point ?
I am not familiar with this service but you might be better looking at a simple REST based approach first and see if it meets your needs.
To answer your question
is parse (https://parse.com/) a good starting point ?
Yes it is.
But I would recommend you to read well on topics such as
REST services
RESTful services vs SOAP - a good article
REST/JSON vs REST/JSON
Services such as parse are called Mobile Backend as a Service (MBaaS).They are ideal to quickly create web services for mobile developers who have little experience with backend development.
A quick search on google on 'MBaaS' will return many services similar to parse and most offer free developer accounts. (With a certain Number of free API calls per second/app)
I have used Apigee similarly & the open source equivalent is Usergrid.
These services will provide a GUI for the developer to create & deploy services and the services are immediately available.
Separate test & production end points will be available.
In addition to basic CRUD operations, these services will also enable easy social network integration, caching & analytics (Depends on service provider)
Features such as security, scalability are built in by the MBaaS provider(Like Parse).
Best I could find was this wiki entry
I I thought "surely there must be more to it than this".
Am I missing something?
From the doc:
What is WebHook?
The concept of a WebHook is simple. A WebHook is an HTTP callback: an
HTTP POST that occurs when something happens; a simple event-notification via HTTP POST.
A web application implementing WebHooks will POST a message to a URL
when certain things happen. When a web application enables users to
register their own URLs, the users can then extend, customize, and
integrate that application with their own custom extensions or even
with other applications around the web. For the user, WebHooks are a
way to receive valuable information when it happens, rather than
continually polling for that data and receiving nothing valuable most
of the time. WebHooks have enormous potential and are limited only by
your imagination! (No, it can't wash the dishes. Yet.)
Why should I care?
As integrated as we perceive the web, most web applications today
operate in silos. With the rise of API's we've seen mashups and some
degree of integration between applications. However, we have not seen
the vision of the programmable web: a web where you as the user can
"pipe" data between apps much like the Unix command line. Some say RSS
is the answer. They are wrong. The heart is in the right place, but
the implementation is wrong. RSS is still useful, but it is not going
to bring us the true programmable web.
We just need a simple way to get data out in real-time to let the user easily do whatever >they wantwith it. That means no polling, no content constraints, and no XML
parsing. That means no RSS. Using HTTP is simpler and easier to use.
PHP is a very popular and accessible programming environment, so it's
likely to be used often for writing hooklets... getting data from a
web POST in PHP is as simple as $_POST['something']. And making the
request to the user script is as simple as making an HTTP request,
something already built-in to most programming environments. In fact,
web hooks are easier to implement than an API.
I'm using this link https://www.google.com/reader/api/0/stream/contents/feed/FEEDHERE?output=json&n=20
to fetch feeds using Google's algorithm. As you can see I'm not adding any other parameters, just fetching the returned data in JSON format. My app will be heavily used hopefully and if I send a lot of requests to this link, will Google block my access or something?
Is there anything I can include, like userip, url for my app (so if they have problem to just contact me) or something else?
The most basic answer to your question is that Google will change its Terms of Service whenever it likes, and you've got no say in the matter. So if it's allowed today, it might not be allowed tomorrow, at Google's whim.
On this issue, though, you seem fairly safe. From the Terms of Service (these is the general document, since Reader doesn't seem to have a specific one):
Don’t misuse our Services. For example, don’t interfere with our Services or try to access them using a method other than the interface and the instructions that we provide.
Google provides RSS and Atom. They provide these feeds, so I assume they expect that they'll be used. They don't say that it's a misuse to point someone else at those feeds, so it looks OK for now, but they could add such a clause at any time.
All online services are subject to the terms and conditions of the providers of those services. So, as others have said, they may be ok with your use today, but they can change their mind any time down the line. I doubt including a URL or email or contact info will help anything, because when these services change, they don't notify every user of the service, they just announce the change publicly, and usually they give several month's notice in order to give users a chance to adapt their applications, but this is not standardized or enforced so there is no guarantee. One example would be the fairly recent discontinuance of the Google Finance API (for which no replacement has been announced).
The safest approach would be to design your app such that this feature that uses google's functionality is decoupled as much as possible from the rest of your app, so that, when or if the availability of the service changes (ie it's no longer available at all) you can adapt your app to use some other source for the feeds with minimal impact to the rest of the app. Design for change and plan for the worst.