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 6 years ago.
Improve this question
I attended a seminar about API basics yesterday and something struck out as odd to me. We covered a basic synopsis of what REST is and what SOAP is and these were defined as architectures of an api.
The way the presenter defined it is that programs have languages and apis have architectures. Is this the proper definition of what an architecture is for an api?
I've looked around on google trying to compare the two terms programming language and architecture and haven't found a clear result.
That statement was almost definitely hand-wavey over-simplification, and was probably only correct within the context of the point he was trying to make.
Architecture is the design and documentation of the high-level functioning of programs and the interaction of those programs.
Programs are implemented in languages, APIs are implemented as programs.
APIs are a documentation of a particular interface to a program, and thus are part of an architecture. APIs are implemented as programs, that themselves have architectures, that fit into a larger system architecture.
I would ignore his statement, it is not helpful to your mental model. Understand what programs are, what languages are, and what architecture is.
REST and SOAP are not even peers. REST is an architectural style, often implemented as HTTP verbs. It is contrasted with RPC style web services, which are often implemented with SOAP. SOAP is a protocol that sits on top of HTTP to implement RPC style web services, it is not an architecture, it is a protocol. REST is not a protocol, it is an architectural element. None of these are a full architecture in and of themselves. SOAP/REST/HTTP/programs/languages all are components in an architecture.
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 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 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 9 years ago.
Improve this question
I'm running some test on those three networking framework: ResKit, NSURLConnection and AFNetworking. And I am seeing that it is not easy to see the differences between the third party libs. What are the major differences between the those? and why? which one is best among these
NSURLConnection is the standard Cocoa class for managing network connection.
That is the base to all these third party libs
The difference is that they are richer,They are written to improve usage of network call in the most easier way and all the basic network call is made possible by custom methods by these libraries
As a dev, Using these will give more Readability ,Performance and icing on the cake is..less code.
Restkit uses AFNetworking for the network communication ,Other than that restkit is a parser for the data coming through the network and is most suitable for RESTful webservices
MKNetworking is one of the other favorites which will have the second place in this list.Got performance and can reduce tons of code
For me,The winner is AFNetworking.It is one of the coolest framework in iOS making my programmig life much easier in network communication.Got great performance also.And uses the latest [or recent] block programming implementation which make the code super easy to read and understand
one more is there ASIHttpRequst : It was a good one but now sadly discontinued
Closed. This question needs details or clarity. It is not currently accepting answers.
Want to improve this question? Add details and clarify the problem by editing this post.
Closed 9 years ago.
Improve this question
The facade pattern is to provide a simplified interface for complex code.
Therefore, it is correct to use it as a wrapper for a system? That would be like a translation map for facilitating the understanding hiding the complexity?
Is it correct then call all Facade as API?
Well the programming interface into any application is the Application Programming Interface, so yes it would be an API, in the same way that your OS has an API keeping you from fiddling with too much memory or abstracting the hard drive - or a game engine has an API acting as a facade for graphics and audio code.
So yes, the implementation of a Facade is an API, but so is any other code which you use as an interface into a more complicated system. (I guess you could ask the question as "are all APIs a facade that just provides a layer of abstraction?" - and you could probably make the argument that it's true).
It's a bit of an odd question to consider however, because depending on who you talk to, these terms may change - we only really use them to represent the idea of abstraction, as we see fit.
Remember that design patterns are not hard fast rules. A Facade is an API that reduces the complexity of using some system. That system may be a single library, multiple libraries, various network clients, etc.
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.
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 work for a insurance company. We have our own development department made-up of almost 150 people plus some providers (outsourcing and custom made apps pretty much). In our company my team have made what we call non-functional logic libraries. That is, software libraries to handle things that are horizontal to all the development teams in our department, e.g. Security, Webservices, Logging, Messaging and so on. Most or these tools are either made from scratch or adaptation of a de-facto standard. For example our logger is an appender based on Log4J that also saves the logging messages into a DB. We also define what libraries to use in the application, for example which framework for webservices to use. We use pretty much JavaEE and Oracle AS in all our organization (with some Websphere Application servers).
Much of these projects have their architecture documented (use cases, UML diagrams, etc) and generally the generated documentation are available.
Now what we have seen is that for users sometimes is difficult to use the the libraries we provide and the are constantly asking question or they simply don't use them.
So we are planning to generate a more friendly documentation for them, so my question is:
What are the best practices or the checklist that software documentation should have?
Something comes to my mind:
API Reference guide
Quick start Tutorial
API Generated Documentation.
Must be searchable
Web Access
What else should it have? Also, based in your experience what is the best way to maintain (keep it up-to-date) and publish this type of documentation?
Keep your documentation in version control too.
Make sure on every page it has a version number so you know where your user has been reading from.
Get a CI server going and push documentation to a LIVE documentation site upon updates.
Do documentation reviews like you would code reviews.
Dog-food it :)
Kindness,
Dan