My customer wants me to create a specification for a future REST API by using Enterprise Architect (SparxSystems). The deliverable should be well formatted text (can be html, docx or rtf). A class diagram should give a picture of the message body.
The only thing I found so far was https://github.com/bayeslife/api-add-in , a plugin for EA to generate RAML and more. Does anybody have a better approach?
The presentation 'Modeling Microservices' by Sander Hoogendoorn contains some interesting slides about modeling a REST API in Enterprise Architect. The presentation is available on slideshare.net. The most interesting slide is slide #75. Here is the picture shown on that slide:
(Class and attribute names are in Dutch. Verklaring means Declaration and Verklaringen means Declarations. But the business behind this example is not relevant.)
It would be nice if someone would have a plugin for Enterprise Architect to convert these class diagrams into Swagger specs (Open API specs).
Update 2019/03/18
Use this plugin and guideline: https://sparxsystems.us/go/restapi/
Original answer
I'm using Enterprise Architect at this moment to model an API. For this projects you have users that are granted a budget to buy certain products. The model is not yet complete, but I'm adding it here as reference.
In EA I added some additional stereotypes: Path, Resource and Representation + a new datatype ParamQuery.
To model the API you create a new class diagram and start by the root of your API as a class of stereotype "Application". Next you add your Resources and Paths. For each Resource you add the necessary GET, POST, PUT etc. operations. If QueryParams are passed along in the string for the GET operations you add them as Parameters for the operation, but as type QueryParam (you need to create it the first time). For the messagebody of POST operations you add a parameter of the class type it represents.
Next you add the "representation" classes, used by the Resources.
I recommend you to use postmanerator service which generate documentation for API automatically just save the API Calls in postman in a collection and pass this collector to this service it generates the documentation for you postmanerator link:
postmanerator
I hope my answer would be useful
Related
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.
Ok, so I'm working on some health related app.
So far, we have our custom database, with Rest API end points, java spring app and oracle database.
Now they are considering to move to the HL7/FHIR specifications. I know pretty much nothing about this framework.
One of our requirements is some sort of audit module recording all sorts of events such as "this patient file got modified by that doctor".
The thing is the framework seems to include an AuditEvent module.
https://www.hl7.org/fhir/auditevent.html
Ideally when a PUT rest call occurs on a "patient" resource, we would create and save a new AuditEvent resource.
The problem I face is how do I know the author of the PUT? The staff member that triggered the patient record update?
There is nothing in their REST recommendations that specifies how we are supposed to cover that aspect? The "author" of a PUT.
https://www.hl7.org/fhir/http.html#vread
Is it specific to how we implement the specifications, some sort of session/security related userID
Many Thanks
PS: there would be other types of events apart from just recording REST calls.
The typical mechanism for identifying users in FHIR is OAuth. There's a bit of discussion on this in the specification here: http://www.hl7.org/fhir/security.html
It makes reference to the Smart on FHIR work which gives some additional guidance.
As well, you may want to look at the Heart work: http://openid.net/wg/heart
The high-level gist is that the authentication happens at the HTTP layer via redirects which then results in a token that gets included in the HTTP header for the PUT and other RESTful operations.
I am trying to implement HATEOS based REST service for hotel booking but have this confusion:
1) How does apart from WADL, the client comes to know about possible operations and their corresponding URI. Should I put all possible operations and URI as response when the client hits the root of REST service?
2) When the client gets a list of all accommodation options in an area, I am returning a list of all hotels in the area he asked about. The response contains:
<accommodation>
<hotel info="http://welco.me/hotel/xxxxxx" price="5000"/>
<hotel info="http://welco.me/hotel/yyyyyyy" price="3000"/>
</accommodation>
But the query I have here is how the client is going to know about other related possible operations like getting the list in sorted order of price?
In answer to your first question, there are a couple of specs for documents that allow clients to discover RESTful APIs.
Swagger
JSON Home
Google use their own Discovery Service, however unlike Swagger and JSON Home, unfortunately I don't think there are open sourced libraries that help you use expose it for your own APIs.
For Your second questions again, I would tend towards clients/developers discovering parameters such as sorting from the Swagger/JSON Home document. However if it is a super strong/important relationship you could also return it in the responses as linked data:
In HAL you can provide a links object with links to related resources.
In JSON-LD you can add a field with a value of the related API url. You may then add an #content to add information describes what that relationship means.
You should use link hints. An older way of doing this, the OPTIONS method, has some longstanding caveats.
Include links that use a custom link relation something like http://welco.me/#sort-by-price where you define the URI to mean whatever you want it to. You should provide some developer documentation at that URI but the client app will never dereference it, it merely uses the URI as an opaque string for equality comparisons.
Most REST tutorials arranged resources as following:
GET /car/ -> list of cars
GET /car/<id>/ -> info about specific car
POST /car/ -> create a new car
but when building web applications for use in browsers, there is a missing link that are rarely discussed, before you can POST to /car/, you need to GET a form for creating a new resource (car). What should the URL for this form be?
I typically used:
GET /car/new/ -> form for creating a new car
POST /car/new/ -> redirect to /car/<id>/ if item is created else show form with invalid fields highlighted
but according to http://www.slideshare.net/Wombert/phpjp-urls-rest this is not a good REST URL. I can see why it's not a good REST, because "new" is really used as a verb and not a resource, but where should the form be then, because GET /car/ is already used for listing cars, so you can't use GET /car/ for the form for new cars.
In short, my question is: "What is the RESTful URL for 'create resource form'?"
On a slightly related note, even in a web service, it is sometimes not always wise to rely on the client knowing the schema in advance, therefore even in web services there could be a need to be a way for client to request the resource's current schema. AFAICS, this as a similar situation with the need to GET a create form (i.e. the form is sort of like a schema which describes how to construct POST query for creating the resource). Is my line of thought here correct?
REST does not care too much about what your URI looks like as long as it identifies one unique resource and is self-describing. Meet those criteria, and beyond that, it is personal preference. Nothing prohibits using a verb in a URI if it makes sense to use one.
In regards to your slightly related note, what you hint at with the form being a schema is media type. RESTful architecture concerns the client and the server both understanding the media types used to represent the application state.
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).
Read more here: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
That is from Roy Fielding, the man who defined REST. In general, your media types should be extensible -- that is, any changes should add on and not break older clients unless necessary.
I always assumed that "form" as such is not a resource, so /<name>/new is okay - forms are not usual elements of APIs. Author of the slides put that on a "bad" list, but didn't provide a correct one - I assume he was so RESTful that he forgot to think about such cases.
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).