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.
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 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
What is the reason why hitting, for example, http:///_vti_bin/UserGroup.asmx?wsdl gives me a not full wsdl specification (if compared with http://msdn.microsoft.com/en-us/library/dd965659%28v=office.12%29.aspx)?
What I mean about not full: it does not contain some of complex types definition, e.g. User (unlike the full one), so this types are no generated by the wsdl.exe.
I have a question in regard of this: is it safe to generate c# web service stub basing on specification from MSDN or this approach is dangerous due to possible changes in contract?
For your first question as to the WSDL not being the same: it really should be equivalent and contain all the types! Whenever you append /_vti_bin/UserGroup.asmx?wsdl to your site's URL, SharePoint should definitely display the FULL WSDL, including the complex type definitions, etc. I just tried it now against my own SharePoint instance and the WSDL returned from http:// mysite.com/ ...snip... /pierre/_vti_bin/UserGroup.asmx?wsdl is pretty much the same size as the one from http://msdn.microsoft.com/en-us/library/dd965659%28v=office.12%29.aspx and a quick check to make sure complex types are in both places confirm that.
To answer your second question: I think you should NOT create your Web Service stubs and skeletons based on the WSDL in the documentation. Instead use the WSDL returned from your site. If you're not getting all the complex types in the WSDL returned from SharePoint, you should fix that issue first.
First thing I would try: download SOAPui (free) and simply plugin the URL that ends with ?wsdl and create sample requests. Maybe you'll run into access issues (UAG or other) but at least you'll know that the WSDL is well formed. If SOAPui can generate the client code based on the WSDL, you can too (using wsdl2java or the wsdl2dotnet equivalent; I can't remember the name of the .net version).
And yes, it's dangerous to copy the WSDL from the docs but I'd be more worried about some things being abbreviated or documentation going stale, etc.
As for the contract changing, I'm using the UserGroup.asmx?wsdl endpoint since 2009 and it still works on newer versions of SharePoint (even after the upgrade to SP2010). And I'm using java as the client code. Microsoft really nailed the Web Services in SharePoint, it was surprisingly easy to integrate our java stack and make calls to/from the SharePoint web services. And it was also very inter-operable with the other tools we use to test Web Services like SOAPui, etc.
We are developing an MDA platform that has support for Web Services. The user can provide a WSDL in runtime and we generate all the artifacts (service interface and implementation for the server, and consumer for the client) using JAX-WS internally.
We want to add validation on the WSDL document provided by the user. Right now the user has to validate that with an external tool like Oxygen, XMLSpy or a web tool, but we want to add that as a part of our system. A nice-to-have feature would be schema validation aswell, including the embedded schemas of the WSDLs.
In JAX-WS (RI) there is support for schema validation in runtime (using the #SchemaValidation annotation) but we haven't found any support for WSDL validation.
We've tried to integrate Eclipse's WSDL validator but it doesn't seem to work for us.
Is there any way of doing this with JAX-WS?
If not, is there any other validation framework that we can integrate?
Thanks
There is a bit of confusion in your question that I need to clarify first.
You seem to want the ability to validate the WSDL (syntax + WS-I) and XSDs, either embedded or referenced externally by the WSDL. On the other hand you bring in #SchemaValidation, which is actually used to validate instance documents.
In a traditional development approach, one might say you want at least the ability to validate design-time artifacts (WSDL+XSDs).
For this scenario then, I would recommend the following:
WSDL: for WS-I compliance testing, please take a look at the test tools section of the WS-I site. It is not clear how the licensing they have with their test tooling would work with yours, but at least it should give you an idea for what to look if it doesn't work for you.
UPDATE: Additional WSDL validation resources:
- Eclipse based, how to use outside Eclipse.
XSDs: if you really need separate validation for XSD files, things may get tricky for a production quality product; WSDL4J is not much help here, and I believe XSOM is the way to go for this kind of job. You have to extract content from the types section as one or more XSD files (could be more than one XSD file, take a look at some examples, Microsoft's SharePoint WSDLs come to my mind as a good test case), assign a base uri for each extracted XSD that matches the WSDLs location, then use XSOM to validate those.
Since you're generating the client, you're most likely not concerned with validating, say of the HTTP headers (SOAP 1.1/HTTP, SOAPAction, if it matches the WSDL operation definition). If you end up developing an interest in that as well, which I call runtime validation, then I would recommend a different layout in your approach (i.e. I would not rely on #SchemaValidation but rather do it through a transparent, and generic, proxy service).
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.
This is quite a concept idea. I would like to create a website that can be extend by different programmer a bit "a la facebook"
Let's me explain i want to develop a very simple core application that for example would store images and i want to develop or allow external developer to develop web app that would be able to act on the image i can take this example of an OS that would store files and you can "install" different program for example to view the files or edit.
How can i reproduce the model in the Web / cloud plateform using API ?
I hope this question make sense to any body.
Thank you by advance
Web Services. Try looking up REST and SOAP.
The Semantic Web is trying to solve this by publishing structured data with common ontologies.
See this example, describing the user's photos as RDF, using the FOAF ontology:
http://www.semanticoverflow.com/questions/201/describing-in-a-foaf-file-assets-of-a-user-photo-album-video-album-etc
The Semantic Overflow website is an excelent resource to find out more about the semantic web in general, and how creating webservices that use a common set of interfaces can allow a greater reach, because tools don't have to be specific to a website.