Generate OpenAPI specification

[gmcfall]

I want a tool that generates OpenAPI specifications for the resources described in my semantic model.

This issue is part of the larger issue #787

Acceptance Criteria

• The tool should look in the Shapes tab, a value of "RestApi" under the column DataSource. This value coupled with the media type of application/vnd.pearson. should specify the intention.

• For each RestApi datasource, there should be end-points that may be generated with the http verbs - GET for retrieval of the resource, POST (for Creating the resource), PUT (replace entire entity), PATCH (for incremental changes) and DELETE (for deletes).

• As described in #805, it is possible to define a hasKey Axiom. When the target OWL class has a single hasKey Axiom which references a single property, then that property will be used for the GET by key method, PUT, PATCH, and DELETE methods.

• An error shall occur if

  • There is no hasKey axiom for the OWL class
  • There is more than one hasKey axiom for the OWL class
  • There is exactly one hasKey axiom for the OWL class, but it is a composite key (which references more than one property).

• For GET http verb, any combination of the property constraint names may be used as query parameters. The datatype of the property constraint should govern how the data needs to be accepted for the query parameter values

• For GET requests, we will not support the ability to filter based on multiple values of a multi-valued property, or based on properties of a related entity. These capabilities MAY be added in the future.

[gmcfall]

@svenk9575 Please add acceptance criteria for this issue.

At a minimum, the acceptance criteria should address the following concerns:

1. How will the tool know which OWL classes need a REST API?
2. How will the tool know what endpoint to use for each OWL class?
3. How will the tool know what query parameters to support?
4. How will the tool know what HTTP methods to support?
5. How will the tool know which Shapes to support for a given class?

[gmcfall]

PATCH is intended to be used when you are changing only a subset of properties of a given entity. PUT should be used if you are completely replacing the entire set of properties of the entity.

I think we ought to support both PUT and PATCH. Is there a reason why you did not include PUT?

[gmcfall]

We need more details that explain how to handle GET requests in cases where one is filtering based on a property that can have multiple values.

Is it possible to specify multiple values for the property in the query? If so, how? Should the multiple values be interpreted as an OR or AND?

I suggest that we not allow multiple values for a single property to be specified, at least initially.
We can add that capability later if it is needed.

[gmcfall]

We need more details that explain how to handle GET requests in cases where one is filtering based on a property whose value is a related entity.

Does the GET method support only restrictions to IRI references to related entities? If the GET method supports filtering based on properties of a related entity, how is that filter expressed in the query string?

I suggest that we not allow filtering based on properties of a related entity in this Issue. We can add support for that capability later.

[svenk9575]

• Agree on the PATCH AND PUT. I missed out the details.

• Agree that the initial version may not allow multiple values for a single property.

• Agree that in the initial version, we may not query related entities.