restful-ma/rest-ruler

The RESTRuler is a tool that evaluates OpenAPI definitions (version>=2.0) using design rule violations.

rest-ruler's Issues

File extensions should not be included in URIs

Description

On the Web, the period (.) character is commonly used to separate the file name and extension portions of a URI. A REST API should not include artificial file extensions in URIs to indicate the format of a message’s entity body. Instead, they should rely on the media type, as communicated through the Content-Type header, to determine how to process the body’s content. (Description from Massé https://www.oreilly.com/library/view/rest-api-design/9781449317904/)

Example

/enterprise/locations/employee/info.json --> Do not use file extension to indicate format preference
/enterprise/locations/employee/info --> Correct way --> define media type throughContent-Type header

Implementation Details

Static check if path ends with a file extension.

a lone single forward slash '/' in a path should cause a Separator Rule Violation

Describe the bug
A path Value contains only a single forward slash '/' which is not a valid path and causes no rule violation

To Reproduce
Steps to reproduce the behavior:

1. create a path in a OpenAPI spec containing only '/'
2. Run Test

Expected behavior
The Separator Rule should identfy a path containing only a '/' as a rule violation

High-Level Project Plan

• Create project plan for the 6 months of the project
• Validate plan in team

415 ("Unsupported Media Type") must be used when the media type of a request"s payload cannot be processed

Describtion

The 415 error response indicates that the API is not able to process the client’s supplied media type, as indicated by the Content-Type request header.

Example

A client request including data formatted as application/xml will receive a 415 response if the API is only willing to process data formatted as application/json.

Above infos from Massé (https://www.oreilly.com/library/view/rest-api-design/9781449317904/)

Implementation Details

TODO

Content-Type must be used

Description

The Content-Type header names the type of data found within a request or response message’s body. The value of this header is a specially formatted text string known as a media type. Clients and servers rely on this header’s value to tell them how to process the sequence of bytes in a message’s body. (Description from Massé https://www.oreilly.com/library/view/rest-api-design/9781449317904/)

Implementation Details

Static check if the media type is defined in content from request operation for each path (https://swagger.io/docs/specification/media-types/).

CRUD function names should not be used in URIs

Description

URIs should not be used to indicate that a CRUD function is performed. URIs should
be used to uniquely identify resources and the HTTP request methods
should be used to indicate which CRUD function is performed.

For example, this API interaction design is preferred:

• DELETE /users/1234

The following anti-patterns exemplify what not to do:

• GET /deleteUser?id=1234
• GET /deleteUser/1234
• DELETE /deleteUser/1234
• POST /users/1234/delete

Implementation Ideas

Search for CRUD keywords in each path segment. Dynamic checking of the parameters is not being investigated for the time being.

See https://github.com/manuelmerkel/Projektarbeit-Master/blob/8909e5d6092767042300f53f931097148c3324e4/docs/Rules/static/CRUD-function-names-should-not-be-used-in-URIs.md for further informations.

If the underscore is used to separate two or more words, the hyphen violation must not be displayed

Describe the bug
If we have paths like /try_something the hyphen violation is displayed together with the underscore violation. The underscore violation already contains a message indicating that a hyphen should be used as a separator, so displaying the hyphen violation too is redundant.

401 ("Unauthorized") must be used when there is a problem with the client's credentials

Description

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all. --> Therefore, provide the 401 response in the definition of the path.

Implementation Details

Check the API definition to see if authentication is defined for requests. If so, the 401 response should be included in the path definition.

Forward slash separator (/) must be used to indicate a hierarchical relationship

Rule with high importance that must be implemented.

TODO

Collect and create documentation.

Bericht über software quality

Context

Darstellung im CLI der software quality Verstöße. Wird auch für #3 benötigt.

Requirements

• #5
• #4

Problem & Solution

Functions

Use Case

Use Case	Description
Actor	User
Precondition
Postcondition
Main path (M)

Underscores (_) should not be used in URI

See https://github.com/manuelmerkel/Projektarbeit-Master/blob/8c4513fd30c8173044fbdbc05771d76e11f2bbef/docs/Rules/static/Underscores-(_)-should-not-be-used-in-URI.md for documentation.

Einlesen einer file

Context

Problem & Solution

Functions

Use Case

Use Case	Description
Actor	User
Precondition
Postcondition
Main path (M)

Map parsed paths to original loc in json/yaml file

Is your feature request related to a problem?
When the OpenAPI definition is parsed, the keys are no longer related to the line of code from the original json/yaml file.

Describe the solution you'd like
Initially, only the path keys are mapped to the original loc from the original json/yaml file. The json/yaml file is searched line by line for the path strings. If a match is found, the line of code is saved with the string.

If further mappings are required, the file LOCMapper.java must be extended.

Additional context
This function is needed for the report and so the user can better fix the violation.

GET must be used to retrieve a representation of a resource

Description

A REST API client uses the GET method in a request message to retrieve the state of a
resource, in some representational form. A client’s GET request message may contain
headers but no body.
Therefore GET requests have to have a non-empty response definition in the OpenAPI spec.

Antipatterns

Additionally following Antipatterns need to be considered:

• A different HTTP Request type is used to retrieve a representation of a resource (#28)
• empty or incomplete response definitions for get requests
• GET request has a request body

GET and POST must not be used to tunnel other request methods

Description

Tunneling refers to any abuse of HTTP that masks or misrepresents a message’s intent
and undermines the protocol’s transparency. A REST API must not compromise its
design by misusing HTTP’s request methods in an effort to accommodate clients with
limited HTTP vocabulary.

Antipatterns

Following Antipatterns need to be considered:

• POST is used to retrieve a representation of resource
• POST is used to delete a resource
• GET is used to delete a resource
• POST is used to create a resource

A singular noun should be used for document names

Description

A URI representing a document resource should be named with a singular noun or
noun phrase path segment.
A document resource is a singular concept that is akin to an object instance or database
record. A document may have child resources that represent its specific subordinate concepts.

Example

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudios contains a violation. claudios would be the name of the document and should therefore be written in the singular => claudio.

Implementation Idea

After a collection must follow a document name non plural. => Split the path in segments keeping the order in which the segments appears from left to right.
Use OpenNLP to tokenize the path segments and check that each even token is not an NNPS (proper noun, plural) or NNS (noun, plural) and check that it is a valid token by checking for singular, proper noun, place, organization with the appropriate library.

  flowchart LR

A[Analyzer] -->|BlockData| B(Violation)
B --> C{Decision}
C -->|Documents Name Plural| D[return list of violations]
C -->|Documents Name Singular| E[return empty list of violations]

KeyMapper nullpointer exception

Describe the bug
OpenAPI parser changes path string --> can´t be found from keyMapper in original json/yaml. For example:

• original path in json: \\v1\\destination_definitions\\get
• parsed path: \v1\destination_definitions\get

--> nullpointer when keyMapper gets loc to path

Screenshots

Lowercase letters should be preferred in URI paths

Description

When convenient, lowercase letters are preferred in URI paths since capital letters can
sometimes cause problems. RFC 3986 defines URIs as case-sensitive except for the
scheme and host components.

Example

http://api.example.restapi.org/my-foldeR/My-Doc contains a violation. my-folderR should be written in lowercase => my-folder. The same applies to my-doc => my-doc

Implementation Idea

  flowchart LR

A[Analyzer] -->|BlockData| B(Violation)
B --> C{Decision}
C -->|Contains Uppercase Letters| D[return list of violations]
C -->|No Uppercase| E[return empty list of violations]

Implementation of a hierarchy that decides which rules should be evaluated first

We need to implement a hierarchy structure that decides which rules should be evaluated first and which rules should not be evaluated due to violations found.
For example if we found a path with Hyphens violation then we don't need to evaluate the SingularDocumentName too, because the structure of the path is not correct and so not ready for SingularDocumentName.

Request methods

Description

Based on the information in the description of each request, we can determine if the request type matches what is specified in the description.

Examples

1. This method retrieves the details of a specific item, such as description, price, category, all item aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery, and other information the buyer needs to make a purchasing decision.
2. This method checks if a product is compatible with the specified item.
3. Merge and analyse sites within a network channel to determine the best server at a given location.
4. Warning! you could lose data. This function will delete the entry from the database and the file from the disk.

In the first example, it is clear that it is a GET type request. The second example might be a little tricky, but "check" is a controller and thus a POST type request. The third example is complicated, but based on Mase's rules, this is a POST request because it has two controllers, which satisfies the POST request assumption. The last one is of type DELETE.

Config file

Use Case

• User only wants to run a subset of the rules --> config file that can be edited via the CLI
• ...

Study Design

Methodological literature: https://xjreb.github.io/swe-research-methods/

Rule: A trailing forward slash (/) should not be included in URIs

Description
As the last character within a URI’s path, a forward slash (/) adds no semantic value
and may cause confusion. REST APIs should not expect a trailing slash and should not
include them in the links that they provide to clients.

Create output file

Context

Output file mit rule violations + Verbesserungsvorschläge + software quality Bericht.

Problem & Solution

• #7
• #6
• #5
• #4

Functions

Use Case

Use Case	Description
Actor	User
Precondition
Postcondition
Main path (M)

A verb or verb phrase should be used for controller names

Description

Like a computer program’s function, a URI identifying a controller resource should be
named to indicate its action.

Example

http://api.build.restapi.org/qa/nightly/register<- Verb is used to express this rule

Implementation Idea

Check if the last pathSegment contains a verb and if the request is of type GET or POST otherwise there is a violation.

https://restapilinks.com/controller/#:~:text=Like%20a%20traditional%20web%20application%27s,%2C%20also%20known%20as%20CRUD).&text=A%20controller%20resource%20name%20is%20a%20verb%20instead%20of%20a%20noun.

Move evaluation artifacts to a different repo to reduce repo size

Working with a repo of this size is cumbersome. My "quick test of the tool" turned into a 15-minute ordeal just to clone the repo (even with --depth 1 -- my corporate VPN is not great).

Would it be possible to split the project into a repo that contains the tool, and another repo that contains the evaluation?

Analysis takes too long

Describe the bug
When analyzing the file: https://api.apis.guru/v2/specs/amazonaws.com/appmesh/2019-01-25/openapi.json the analysis does not terminate (at least within a reasonable time).

Check base path

Refactor code --> RestAnalyzer path list (with base path and query parameters) to rule class.

Bericht über rule violation

Context

Darstellung im CLI der rule violations. Wird auch bei #3 benötigt.

Requirements

• #5
• #4

Problem & Solution

Functions

Use Case

Use Case	Description
Actor	User
Precondition
Postcondition
Main path (M)

Hyphens (-) should be used to improve the readability of URIs

Description

To make your URIs easy for people to scan and interpret, use the hyphen (-) character
to improve the readability of names in long path segments. Anywhere you would use
a space or hyphen in English, you should use a hyphen in a URI.

Example

http://api.example.restapi.org/blogs/markmasse/entries/thisismyfirstpost should be => http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post

Implementation Idea

  flowchart LR

A[Analyzer] -->|BlockData| B(Violation)
B --> C{Decision}
C -->|names in path segments| D[return list of violations]
C -->|No names in path segments| E[return empty list of violations]

A plural noun should be used for collection names

Description

This problem is related to #15 . They can both be implemented in the same branch, since the way of checking their violations is similar.

Erkennung von rule violations

Context

Openapi files must follow certain rules. In the paper by Kotstein and Bogner [1], rules from Masse's book [2] are categorised into medium and high importance and each is assigned a software quality attribute. After reading an openAPI document #5, these rules should be validated and rule violations detected.

Requirements

• #5
• Dynamic rules
• Static rules
• Documentation of implemented rules in the repo (https://github.com/manuelmerkel/Projektarbeit-Master/tree/main/docs/Rules)

Implemented rules

• #9

Problem & Solution

• Dynamic rules are difficult/not automatically analyzable

[1] https://link.springer.com/chapter/10.1007/978-3-030-87568-8_10
[2] https://www.oreilly.com/library/view/rest-api-design/9781449317904/

Get state of analysis

Describe the solution you'd like
State which rule is currently being analysed and how long it takes to analyse it.