Supposed you need to interact with/integrate 5+ different web service sources instead of tables from the database.
In first lane each WS supports read methods like search,list and single view (in short, no CUD from CRUD). Write access should also take place later.
What would be your approach to integrate those to extbase?
I'd like to stick to the conventions of models and repositories. In this case, i think we need to use Models and CustomRepositories. Should the repositories interact directly with the webservice or should we think bigger with an PersistenceManagerInterface implementation and extending the Generic/Query to e.g. paginate on the results by extbase conventions? What is about TypeConverters and PropertyMappers for linking between controller actions with the models "as parameters".
How could a mapping from JSON to the models look like? A TCA configuration is required for the DataMapper, but this is not available because no DB is used, so it cannot be used.
Where should you start?
I am looking for an easy-to-implement solution for form-based ontology editing and I wonder if there are any active projects and which of them is the right path to follow.
I need to create instances of an ontology (lets call it ontology A) using forms (either web or desktop) and store them in a triple store (e.g. Virtuoso). I would like to hide as much details as possible regarding the ontological relationships between the entities defined in ontology A and provide a plain simple user interface for CRUD (Create-Retrieve-Update-Delete) operations based on the entity schema defined in ontology A.
For example, I have found two possible solutions in the protege ecosystem:
PropertyFormPortlet It is not a live feature in the current webprotege version.
facsimile project
As described in the respective paper this is a solution that has been implemented for a specific context. Therefore, adapting it to another domain would not be as straightforward as I would like.
I wonder, is there another solution (even out of the protege ecosystem) that could facilitate such a form-based ontology editing. Could somebody provide some guidance?
Just in case someone lands in this question, I write down my conclusions. Practically, none of which I tried worked, but still I found out some interesting things.
OpenLink Structured Data Editor:
OSDE is a browser plugin which aims at populating RDF graphs in the form of files, based on Linked Vocabularies. In my case it didn't work as my locally hosted ontology cannot play the role of a "Linked Vocabulary". However, OpenLink team said they will work on it.
OData2SPARQL:
In our test, the WebIDE did not manage to create the forms out of the box as suggested by the respective video tutorial. However, we managed to use OpenUI library as a client of the OData services automatically created by OData2SPARQL, providing a web service interface for our ontology.
Ontowiki:
In our test environment, OntoWiki partially worked. We could save data but there were some bugs when trying to add properties etc. OntoWiki developers said that they plan to refactor in order to actively support it in newer hosting settings, but this is not the case right now.
I added custom metadata through xml configuration specified in their wiki ... I could see the aspect I added in the /share application in manage aspects but it is not listed in /alfresco app and when i am uploading the document using the rest api it says unable to find the field i added ..
Share and old Alfresco Web Client have different configurations.
Check these resources out for more information:
http://wiki.alfresco.com/wiki/Web_Client_Customisation_Guide
http://wiki.alfresco.com/wiki/Displaying_Custom_Metadata
Please read this tutorial which covers creating custom content types and aspects and exposing those to both the Share (/share) and Explorer (/alfresco) web clients.
It sounds like you may have multiple problems, though, beyond configuration, because the REST API should be able to see your custom model, if it is defined correctly, regardless of whether or not it is configured in either of the two web clients.
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'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.
Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.
Some specific tools that are helpful for generating documentation like this:
Swagger
An open spec for describing REST APIs [ github ]
Tools for auto-generating
Documentation
Code for your API
Donated to the OpenAPI initiative and renamed OpenAPI in 2015
Mashery
An open source project [ github ]
Tools for generating
Documentation
An exploration interface for your API
Apiary and API Blueprint
Write the API description in a DSL within markdown
Tools for auto-generating
Documentation
Mock server
Seems to be focused on ruby+mac devs
RAML
A spec for describing REST APIs [ github ]
WADL
A spec for writing discoverable API docs with XML
Some discussion comparing WSDL and WADL
APIgee
A commercial product with some documentation features
3scale
A commercial product with some documentation features
miredot
Commercial REST API documentation generator
Java specific
I've been using http://apiary.io, which is pretty nice. You can also export the API documentation to github.
In Roy's post here he states
A REST API should spend almost all of
its descriptive effort in defining the
media type(s) used for representing
resources and driving application
state, or in defining extended
relation names and/or
hypertext-enabled mark-up for existing
standard media types. Any effort spent
describing what methods to use on what
URIs of interest should be entirely
defined within the scope of the
processing rules for a media type
(and, in most cases, already defined
by existing media types).
A good ReST documentation would mean documenting your media type and only your media type.
In a typical scenario, you'd produce a document like so:
The Acme Corp XML formats
Link Discovery
Links to various resources are described in a document that can be found by issuing a GET or HEAD request to the server on a bookmark URI (typically the root of the server, http://www.acme.org), and looking for an HTTP Link header:
Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml
where the rel part is the link relationship, and the xxx is the URI for which the relationship has been established.
Link Relationships
This document defines the following relationship names:
http://rel.acme.org/services
The link relationship describes the list of links that can be navigated.
http://rel.acme.org/customers
The link for which this relationship is used is the list of customers.
Media Types
The application/vnd.acme.services+xml is a document with an xml serialization that describes a list of links an application may want to process.
<links>
<link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>
The applcation/vnd.acme.customers+xml is a document with an xml serialization that describes customers.
Example documents:
<customers>
<customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>
etc...
The point is to give a way to the developer to follow the links you define. First find the link to the index so they can get the list of things they can navigate to.
Once they discover that document, they discover that they can see a list of customers at a certain Uri, and can do a GET against it.
If they find a customer of interest, they can follow the link defined in /customers/customer/#href and issue a GET to retrieve a representation of that customer.
From there, your media type could embed actions that are available to the user, using more links. You also have the additional option of issuing an OPTIONS request on the resource to know if you can allow deleting the resource, or a PUT if you can save the document back after modification.
So a good documentation doesn't ever:
give static links
give interaction such as "you can issue POST on Customer with this media type and that will mean the move operation". The client should issue a POST against Customer only because your XML document has specified it that way.
The point of all this is to achieve minimum coupling between clients and servers. The client can be very smart in displaying and discovering resources (showing forms and god knows what else), but is totally dumb as to what the actual workflow is: the server decides.
At my company, we've been very happy using WADL, Web Application Description Language. Wikipedia describes it as: "an XML-based file format that provides a machine-readable description of HTTP-based web applications". I find raw WADL easy to write, read, and understand, and it maps directly to RESTful concepts. The official project provides a simple spec, XSD and RELAX NG schemata, and Java tools.
A number of tools and resources exist for working with WADL, including:
wadl_stylesheets, XSLT stylesheets to create HTML documentation from WADL files
Restlet, a Java framework for building RESTful servers and clients, includes a WADL extension
A tip: try including human-readable documentation, such as descriptions, concepts, getting started, usage tips, etc, in the WADL document's doc element by including HTML elements, using the XHTML namespace. It can make a big difference!
You might find rest-tool useful.
It follows a language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs. It also provides a cook-book however it is in a very early stage, but its content is continuously growing.
The services you just described can be immediately used, so it is also good for experimenting.
Initially, we went for static documentation of resources but just had to field too many questions. Eventually, we moved to using Live documentation pages using IO/Docs (actually a fork).
Been working great.
To create understanding/documentation, heavyweight solutions aren't always needed. Examples of (great) heavyweight tools are: IO/Docs / Apigee (although great tools).
For tiny projects that already have a docchain setup (doxygen/phpdoc/phpdoctor/custom/etc) I use the following shellscript to just include the page in the full generated documentation:
https://gist.github.com/4496972
A demo: http://pastie.org/5657190
It just use custom comment-tags in your sourcecode.
It can also be a nice starting point for documenting any sourcecode (language).
In a MVC application, what are some of the components that make up the application. What tools and functionality is missing that you would like to have. Regardless of the server-side language, what would you want?
I see a lot in my code where I code some much functionality that it seems should already be there. I looked at Google web toolkit and they seem to get it right. Widgets are widgets and you simply add them to your application.
For example. I work with J2EE apps but in other languages, the components are the same.
Controller Objects
Controller handlers, defined by methods in the controller objects.
Configuration files defining the URL mapping and settings.
Template server page files (e.g. JSP/ASP files).
Configuration files defining O/RM mapping between application objects and the database.
Configuration files defining the database connection properties.
JavaScript libraries (e.g. jQuery)
Logging configuration files
Resource message bundle files
Validation configuration files or code
Middleware components and objects (EJB configurations, JMS/Messaging configurations, etc).
Credit Card or other middleware connectivity APIs and libraries.
Anything else you can think of?
Built-in Unit Testing Component
I think one thing you're missing from that very exhaustive list is the automatic binding of request properties to form objects, and the saving of these objects to the session where appropriate. Form objects here being the object on the server that represents the current state of the HTML-based for displayed to the user.
I think scaffolding and automatic admin interfaces are very nice features too, that I dont want to miss ;)
You've made the assumption that all MVC applications are websites. MVC is widely used for more than just web apps so things like URL mappers, template server pages and "Server side" languages are not associated with the MVC pattern, so much as a particular implementation and adaptation of the MVC for use in web apps.