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 7 years ago.
Improve this question
I am new to web application design. It seems contemporary web applications usually take this form:
Front-end leverage various JS frameworks to built the UI.
Then front-end invoke back-end web services with JS to exchange XML or JSON data and update the UI accordingly.
Back-end is separated into tiers and expose Web service APIs to whatever external.
Web service APIs also exist for the communication among the back-end tiers.
So the web service APIs should be the critical part to design.
How do we design it? To be specific:
What data/materials are needed to start the design with?
What tools can we use? (I heard about some tools to convert XML into classes.)
And what does the final output of the design look like?
ADD 1
To be specific, suppose there's requirements like this:
Customer should be able to upload and delete certain files from the
file repository.
Customer must be authenticated before modifying the files on file repository.
How can I convert it into detailed API spec, and then concrete class definition?
A related link: http://piwik.org/blog/2008/01/how-to-design-an-api-best-practises-concepts-technical-aspects/
ADD 2 - Regarding RESTful
After reading some books, I came to this:
RESTful architecture is just one of the many ways to integrate
applications. It leverages Web standards in the hope of making the
integration simple and natural. Resources are identified by URLs,
manipulated with HTTP methods, and transferred in certain serialization
form at the convenience of the integrated parties.
To create a Web API (i.e. RESTful service), you need to follow REST principles. I think that this link could give you some hints about the design of RESTful services / Web API: http://restlet.com/blog/2015/03/16/designing-a-web-api/.
To be short, RESTful services should leverage HTTP methods they are designed for:
method GET: return the state of a resource
method POST: perform an action on the resource (creation of an element in a resource list, ...). Be careful not to use an action name within URLs (something like /elements/some-action-name) because it's not RESTful.
method PUT: update the complete state of a resource
method PATCH: update partially the state of a resource
method DELETE: delete a resource
You need also to be aware that they can apply at different levels, so methods won't do the same things:
a list resource (for example, path /elements)
an element resource (for example, path /elements/{elementid})
Other important things you must consider are:
To use status codes to tell the client if the request is sucessful (2xx family), fails because of the client (4xx family) or of the server (5xx family)
To leverage HTTP headers. For example, the header Content-Type for the type of content used (application/json for JSON for example) and Accept for content negotiation if needed...
Otherwise there are some formats like Swagger and RAML you can leverage to craft your Web API. A tool like Restlet Studio could a good help to create the structure of your REST service online, get the corresponding Swagger and RAML contents, and even generate server skeletons or client SDKs. You can notice that this tool only follows REST principles...
Regarding security, you need to leverage the Authorization header. There are several strategies:
Basic one. The username / password are encoded with Base64 and sent in the header.
Token-based one. You could have a look at this link for more details: https://templth.wordpress.com/2015/01/05/implementing-authentication-with-tokens-for-restful-applications/
OAuth2. See this link: http://www.bubblecode.net/en/2013/03/10/understanding-oauth2/.
Regarding file upload, you can leverage multipart contents. See this link: http://restlet.com/blog/2015/10/27/implementing-file-upload-with-restlet-framework/. We use the Restlet framework but you might pick up some generic hints...
Hope it helps you,
Thierry
In my opinion the concept of a Rest-full API is a little blurry, I would advise you to take a look at this article http://martinfowler.com/articles/richardsonMaturityModel.html
Not many public rest-full api's actually achive the discussed level 3. The general idea it to model your api around the "resources" your application deals in and respect the proper http verbs.
As for tools I kinda like https://apiary.io/ it helps you build an API and can provide mock responses as well
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 8 years ago.
Improve this question
I am studying for a developer certification and I have some doubt related to the general concept of REST and REST Web Services.
From what I can understand REST is more related to software\network architecture style consisting of guidelines and best practices for creating scalable web services respect to a specific technology (differently from SOAP that is a specific implemented network protocol).
The first doubt is: "is REST related only to web services implementation or can be related also to other purposes? If it could be related to other purposes what are?
So from what I can understand using this REST style the messagges are send and receive directly using the HTTP protocol without using an intermediate protocol as SOAP.
I know that REST is statless (does not maintain information about previous states) so if I use the REST style I can't use the Http Session or coockies to mantain informations about what happens before. If it is true, why? what is the benefit of a statles managment? What is the difference with SOAP? Is SOAP statefull? (it seems to me not but I can say wrong things).
Using REST style the resources are modelled as noun, for example:
http://mybank.com/banking/accounts/123456789
And then I can perform a limited set of operations on these resources, operations described by: GET, PUT, POST, DELETE
Reading on the course documentation it say that these operations are the default operation in case of the architecture works over Http protocol. So are these operations the only operations that I can perform or can be used others? Can you explain me this thing?
Maybe I have a big gap in the Http protocol knowledge, I only know that Http protocol only supports the POST and GET operations. So what exatly are these PUT and DELETE operations? Are Http protocol specific operations as GET and POST? What is the difference between PUT and POST? and why REST architecture use PUT instead POST?
Tnx
REST describes guidelines and best practices to design an efficient architecture for the Web.
Can I suggest you to read these two posts? I think that they could help to answer deeply your questions about resources, operations, representations...
https://templth.wordpress.com/2014/12/15/designing-a-web-api/ - Designing a Web API (i.e. RESTful Web services)
https://templth.wordpress.com/2015/01/05/implementing-authentication-with-tokens-for-restful-applications/ - How to handle security for RESTful Web services
Yes, normally RESTful applications are stateless. This means that you should keep states on the server-side. In the case of security, you need to authenticate users at each request. That said, since Cookies are part of HTTP, you could leverage them within your application.
Hope it helps,
Thierry
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 8 years ago.
Improve this question
I have a database which I consider to be my application and a website acting as a user interface for that application. It is now time to add more user interfaces to my application (phone apps etc).
Keeping this in mind, I have come up with a web service architecture to feed data to all my user interfaces. I would like to sanity check this with the brains on stack overflow. Btw - this is all Azure hosted.
Database, as is.
Core web service - this handles all important methods and invokes the main processes on the DB. For example, registration. This will also automatically queue emails to be sent, etc.
Web Services for each UI (website, phone app) - these are specific methods for the UI data calls - e.g. GetDataForRegistrationPage - specific to the website and not needed for the app. The app would have different requirements.
So far I think this is reasonable though I'm interested in your opinions. I would like a bit of help with the next bit: how they communicate.
I would like the Core web service to be a WCF Service that can ONLY be accessed on named pipe endpoints - ensuring that only the client web services can communicate with them (I can guarantee they are on the same machine).
I would like the Client Web Services to bind to their applications by TCP or http. The website will be on a separate machine but on the same network and so is a good contender for TCP. The apps will of course be on clients and would be best as http I believe.
I am worried that I've introduced too many steps with this design. Using registration as an example, the user would register using the website page which goes to the web server which would invoke the registration method on the website web service, which would invoke the registration method on the core web service, which would invoke registration on the database.
Thank you for your thoughts!
(I posted the below as answer but got told off. If we really want to be anal about this then I guess no one should have posted anything as answer as there is no real answer - I was asking for opinions, but anyway...)
Just in case it is of any interest to others having similar design questions. I have decided to get rid of the core service idea and just use a class library shared between each client service.
Pros: Easier to develop, one less complication (setting up named pipes seems impossible to me) and one less process to get involved (even if it is on the same machine).
Cons: Each service now HAS to be on Azure, otherwise it cannot access the Azure storage facilities. I will be using the queue to schedule emails. With the first approach I could have potentially hosted one service on a completely separate platform.
Feel free to comment with any ideas or observations. Thank you for the input, Ramiramilu and Markus.
Your approach seems to provide a good separation of concerns. Depending on the size of your project, it might be a bit too much. If you are looking for a way to simplify your architecture, here are my thoughts:
Client WebServices
I'd propose to analyze how big the differences of the Client WebServices really are or whether it is possible to set up a common service for all clients. Even if you were able to move a lot of shared code to the Core WebService, you'd have to implementent very similar interfaces over and over again. Of course this implies that there won't be a specific WebService that is tailored to the needs of a specific client. If you build on WCF, you can also offer services with different bindings so that e.g. the WebSite accesses the service using a NetTcpBinding whereas another client communicates with the same service over a SOAP interface (WebHttpBinding or WSHttpBinding whichever fits your needs). This would be much more efficient because you'd not have to implement common building blocks like authentication and authorization for each Client WebService.
Also you might want to have a look at ASP.NET WebAPI and consider building a REST API that should be accessible from all devices - though it is as efficient as a TCP binding. You could also host your Web API in the WebSite project so that you can use it both from other client and for AJAX requests. As your WebSite is accessible from the internet anyway, this is also a good approach from an infrastructure point of view.
Core WebService
You could substitute a class library for the Core WebService. The Client WebService(s) can integrate this much easier without having to deal with additional complexity, e.g. for authenticating at the Core WebService.
As you want to host the Core WebService on the same machine anyway, I'd only build a service if there is a strong reason for it. I can't come up with one now.
Conclusion
If your requirements are only to add some clients with a limited set of capabilities, I'd suggest to add a Web API to your WebSite project and access it from the other clients. See this link for more information.
I'm currently developing a web application, that relies heavily on mobile and desktop clients consulting the web server for information. This can be accomplished nicely making a RESTful API available to handle this. So my idea is to have an application acting as the "platform" which handles all the real business logic and database information behind the curtains.
My plan is to make the platform using symfony2 and OAuth 2.0 authentication mechanisms, combined with RESTful web services.
Now my real dilema comes on the website component. Ideally I would like to think of the website as yet another client that asks this REST platform for information, and completely separate it from the platform itself.
To make it a little bit more clear, let's say we are making a blog with this architecture, so one would have a "platform/backend" that provides a rest service to list articles, for example: /articles/5. This on the backend, and with symfony2/doctrine means that the app has an Article model class, and these can be requested from the DB. A simple controller queries for the Article number 5 and returns all the information in JSON format.
Now the website on this example, could just do the easy thing and also have an Article entity and just query the database directly, but I think it would be cleaner if it could just talk to the platform through it's REST api and use that information as a "backend" for the entities.
So the real question would be, is there anyway to support this kind of design using symfony2? Have entities rely on a REST api for CRUD operations? Or I'm just better off making the platform/website a single thing and share a "CoreBundle" with all the generic entities?
There is nothing in Symfony that prevents you from doing you want.
On the client side you could use Backbone.js or Spine.js.
Have a look at FosRestBundle, it makes your life much easier to create api:
https://github.com/FriendsOfSymfony/FOSRestBundle/blob/master/Resources/doc/index.md
Can some people offer some light on the following questions? I believe that the following questions are very much debatable, but I just want to know the mere facts which will enlighten me & of course many others viewing this general question post.
Why does Magento API produces Web Service Responses in XML format & not in JSON format? There should be some advantages in producing the responses in XML format. I want to know those advantages mainly.
In Magento terminology, there are two API versions mentioned - "Normal API" (api/soap) & "API v2 (api/v2_soap)". What's the difference (mainly the advantages) between these two versions, & where does WSDL fit in?
If I'm to create a new Web Service, should I be targeting SOAP v1 format, or the SOAP v2 format, or both of these formats?
Can the Web Service create a general definition of WSDL, based on my requirements, in Magento? What I want is that I want to know whether the "wsdl.xml" file (residing in the "etc" folder of the Magento module) for any particular Magento API module can be generated dynamically? If I provide my required API method name, along with all the property names, types, and also the Response data types, then will I get the "wsdl.xml file dynamically generated with all the Complex Types & Methods & Messages properly mentioned?"
If possible, please provide some good links, from where this spider-webs of Magento Web Services can be thoroughly cleared.
Also, please consider my expertise in this field of Web Service as a novice one, so that based on any valuable input, I can re-frame the question.
Help appreciated & thanks a lot to everybody.
My Main point of asking this question is that I want to make new custom APIs which can be used by any systems, whether it be ERP / CRM / SAP / Cloud / anything in general.
P.S.
I tried posting this question in the Programmers Stack Exchange area, but due to the lack of available required tags (like magento, wsdl & soap), I had to post it here. If possible & required, please transfer this question to proper stack exchange area.
API is not for ajax(frontend), but to integrate Magento (frontend shop) with different ERP, CRM, SAP (backend tools) systems - to import data and get reports. That's why it's using XML.
This is not magento's terminology. This is done mainly for legacy support. So you have to use lates one - v2.
What means general definition of WSDL? WSDL describes published functionality - available calls/resources. If you don't need it you need to overwrite configuration files to not publish everything but only necessary ones or do this form admin area.
Could you tell more clear and more technically what do you need to do with API?
The API works great for normal PHP programming where you want to get something out of Magento. 'Normal' API works fine with PHP, furthermore, the resultant XML is very easy to work with in comparison to the XML that gets churned out by other APIs.
Some people have said that the Magento API is slow, which it is. However, if you move the same code into a Magento program then it still takes forever, the API code isn't much of a burden.
I used WCF to create a restful web service in .NET, by means of a .svc file. The web application automatically produces a WSDL file. AFAIK, the WADL is more natural for a restful web service.
How could I create a restful service in .NET (preferably with wcf) that produces a WADL description?
Note An answer like "RTFM" is accepted, as long as you indicate a suitable manual/tutorial.
This is an old question but having consumed restful services with WADLs they do offer some value. You can import them straight into SOAPUI and it will build a test suite for you automatically. Secondly they tend to contains all the required XSDs for XML based services and are useful for automatically building serialisable classes that your endpoints accept and receive.
Looks like REST Describe & Compile should do the trick.
On the WADL developer site Marc Hadley
maintains a command line tool named
WADL2Java. The ambitious goal of REST
Describe & Compile is to provide sort
of WADL2Anything. So what REST
Describe & Compile does is that it:
Generates new WADL files in a completely interactive way.
Lets you upload and edit existing WADL files.
Allows you to compile WADL files to source code in various programming
languages.
Forgive me for answering a question with a question, but do you really want to do REST? REST really has no need for things like WADL.
Update:
The "hypermedia constraint" (aka HATEOAS) dictates that the user agent discovers content based on links embedded in previously retrieved content. It really is unnecessary to have a separate document that describes all the available content.
Imagine using a web browser to go to a site and instead of going to the home page and navigating from there, you are presented with a page which is a list of all the URLs on the site. You must then looks through the list of available urls, choose the one you are interested in and copy it into the address bar.
WADL is effectively you list of site urls. You just don't need it if your main content is linked together.
Linking content instead of using a WADL "site map" has other advantages. The available links can be dynamic based on particular data values in the content. This capability can vastly reduce the complexity of clients, because the client no longer needs to host the logic to decide when it is allowed to follow a link.