belgif
example REST mock API + absolute URIs in guide
In GitLab by @pvdbosch on Apr 25, 2018, 12:28
development of a REST mock API, serving as an example for the REST style guide
Examples in the styleguide should be replaced with samples from the REST mock API; and using full URLs instead of relative ones.
In GitLab by @pvdbosch on Jun 28, 2018, 10:29
requirements:
- topic: enterprises, establishment ~ KBO; linked to person
- document, collections operations, incl long running tasks, pagination, non-CRUD operation
- caching
- i18n
In GitLab by @pvdbosch on Jan 22, 2019, 11:47
The API used for internal Smals trainings is going to be used as mock API.
@smals-wisa , could you share it on gitlab in a new project under the rest group? We can then review it from there.
There still will be some work to publish it under gCloud, as it currently has some Smals-specific dependencies.
In GitLab by @pvdbosch on Dec 11, 2019, 15:03
A Smals developer will work on this. Try to get it done in two months, then update examples in guide. @wsalembi , can you share the code (mainly Swagger) for review?
- /doc/schemas/{name} can be removed
- align terminology:
- cbeNbr => enterpriseNumber
- companies => organizations or registeredOrganizations
- cbe often uses 'entity' in its doc, but in fedvoc international terminology '(registered)Organization' was adopted
- nssoNbr => employerId
- or nssoNumber if temporary and provincial/local authority are not excluded
- validate swagger by other WG members
Future:
- make publicly available
- add other operations/features that illustrate the REST guide
I did a review of the Swagger:
- beginDateGT => beginDate_gt cfr #18 (guideline not published yet, but was confirmed a long time ago in WG)
- names and types:
- various fields to align with fedvoc, like zipCode => postCode and nossNbr => employerId. I think you can let Veronique review this to get a full list. There's an EmployerId field in openapi-employment-identifier (but still in beta).
- use the belgif openapi files with common types (from sister GitHub projects)
- country field: is it NIS code or ISO code? CountryNisCode can be used from openapi-location. The ISO codes are still in beta (v1beta).
- region: is this a name or a code? Functional WG standardized on ISO 3166-2:BE codes. For the BE regions, there's a BelgianRegionCode type in openapi-location
- state: "inactive" instead of "nonActive"?
- "GET /employers" without pagination or query params: seems a bit weird to be able to return all employers in a single response. Maybe make it an example for cursor-based pagination?
- POST /employers : in JSON body, nssoNbr field can be "readOnly: true" to indicate it shouldn't be specified in request
- GET /appendices/{appendixType} => seems to regroup multiple types of unrelated reference data => better to split them and put them in /refData/ e.g. "GET /refData/employerClasses/{employerClass}"
- /health: to be updated with standardized health check in REST guide
- GET /companies: add paging properties in JSON response like specified in https://www.gcloud.belgium.be/rest/#pagination (page, next, prev, maybe the optional first/last links)
other nice-to-haves:
- controller resource
- add caching to a GET (ETag and CacheControl)
- example of an embedded resource
Hello @pvdbosch, Thank you for the remarks. I have started working on the improvement of the Swagger and will also take your remarks into account.
- changed nssoNumber to employerID
- changed cbeNbr to enterpriseNumber
- updated /health with new guidelines
- I have also added an operation DELETE /employers to show have to remove a (filtered) collection.
I will plan next week a meeting with Veronique for her input, and I will also add your remarks.
I hope to have it ready for the next rest group of 25/11.
Hello @pvdbosch , @wsalembi,
Thank you for your remarks.
Concerning the first part of this issue (example REST mock API), here is a summary of the changes that I made:
--> swaggerSuggestion.yaml
- New file to replace swagger.yaml
- Changed "cbeNbr" to "EnterpriseNumber", also description and type, pattern
- Changed "NssoNumber" to "EmployerId", also description and type
- Changed "beginDateGT" to "startDate_gt" L.107
- Changed "Company" to "RegisteredOrganization"
- Removed get /appendices/{appendixType}
- Added get /refData/employerClasses
- Removed get /appendices/{appendixType}/{value}
- Added get /refData/employerClasses/{employerClass}
- Added pageSize as query parameter for get /employers
- Added controller POST /employers/{employerId}/link
- Updated /health with new guidelines
- Added new endpoint DELETE /employers to show how to remove a (filtered) collection
--> Address.yaml
- Changed "region" to "belgianRegionCode" & added enum (BE-BRU, BE-WAL, BE-VLG)
- Replaced "locality" with "municipalityCode" and "municipalityName"
- Replaced "street" with "streetRrnCode" and "streetName"
- Removed "countryName" (not an approved term)
- Added countryNisCode
- Changed "houseNbr" to "houseNumber"
- Changed "postBox" to "boxNumber"
- Changed "zipCode" to "postCode"
--> Common.yaml
- Changed "CbeNbr" to "EnterpriseNumber", also description and type, pattern
- Changed "NssoNumber" to "EmployerId", also description and type
--> Company.yaml
- Renamed to RegisteredOrganization.yaml
- Changed "cbeNbr" to "EnterpriseNumber", also description
- Changed "beginDate" to "startDate" (based on API Schema's)
--> CompanyCollection.yaml
- Renamed to RegisteredOrganizationCollection.yaml
- Changed "cbeNbr" to "EnterpriseNumber"
- Changed "nonActive" to "inactive"
- Added paging properties for offset-based pagination (page, pageSize, next, prev, first, last, self)
--> Employer.yaml
- Changed "cbeNbr" to "EnterpriseNumber"
- Changed "NssoNumber" to "EmployerId"
- Changed "Company" to "RegisteredOrganization"
- Added allOf & "readOnly: true" to employerId, to indicate that it must not be sent as part of the request
--> EmployerCollection.yaml
- Changed "cbeNbr" to "EnterpriseNumber"
- Changed "NssoNumber" to "EmployerId"
- Changed "Company" to "RegisteredOrganization"
- Added paging properties for cursor-based pagination (pageSize, next, prev, first, last, self)
--> AppendixCode.yaml --> Removed --> AppendixCodeCollection.yaml --> Removed --> EmployerClass.yaml --> Added
Let me know your remarks and if there are still things to add or modify.
Later, when the first part is approved, I will work on the second part (examples & absolute URIs in guide).
I got some broken references when opening swaggerSuggestion.yaml:
There was an error while processing your files. Please fix the error and save the file.
#/paths/~1refData~1employerClasses/get/responses/200/schema/items: JSON Pointer points to missing location: ./schemas/EmployerClasses.yaml#/definitions/EmployerClass
#/paths/~1refData~1employerClasses~1{employerClass}/get/responses/200/schema/items: JSON Pointer points to missing location: ./schemas/EmployerClasses.yaml#/definitions/EmployerClass
#/paths/~1registeredOrganizations~1{enterpriseNumber}/put/parameters/1/schema: JSON Pointer points to missing location: ./schemas/RegisteredOrganization.yaml#/definitions/RegisteredOrganization
#/paths/~1registeredOrganizations~1{enterpriseNumber}/put/responses/200/schema: JSON Pointer points to missing location: ./schemas/RegisteredOrganization.yaml#/definitions/RegisteredOrganization
#/paths/~1registeredOrganizations~1{enterpriseNumber}/patch/responses/200/schema: JSON Pointer points to missing location: ./schemas/RegisteredOrganization.yaml#/definitions/RegisteredOrganization
Some more feedback:
- response status codes should be string instead of number: e.g. "200" instead of 200 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responses-object-example
- Could use /health path in common-v1.yaml instead of your own. Or at least use HealthStatus from common-v1.yaml (some tools have problems with referencing paths from common schema) and drop the produces: text/xml. If "type" query param needs to be kept, should mention this is an extension, not part of the REST guide standard.
- "404" doesn't always have a response body schema, while Problem can be used to return a resourceNotFound JSON problem body
Hello @pvdbosch
Thank you for the review. OK, I fixed the broken references. (I use https://editor.swagger.io/ and didn't get an error about the broken references.)
About the other remarks:
-
OK, I adapted /health & HealthStatus according to common-v1.yaml. (At first, I copied the health from another project that was approved, so I assumed it was OK).
-
OK, I adapted 404 to always return a Problem schema.
-
About this:
response status codes should be string instead of number: e.g. "200" instead of 200
Isn't this in conflict with the problem Json schema? status: type: integer format: int32 description: The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600
https://github.com/belgif/openapi-problem/blob/master/src/main/swagger/problem/v1/problem-v1.yaml
Can we have min & max values on string?
Hi, @smals-chlo , definition of status code as integer in the Problem JSON schema is OK, but in the Swagger schemas where you define the JSON schema for each response status code, it should be a string instead of integer. The status code is a property name in this case, which should be a string.
cfr example in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responses-object-example
Not all editors detect this issue, but StopLight Studio does. StopLight also detects broken references; and swagger-ui-watcher does as well.
Hi @pvdbosch , @wsalembi,
Here is the last version after the remarks:
Swagger #19.zip It is also added on this page of the Rest group, so that Veronique can see it. https://confluence.smals.be/display/REST/Swagger+Suggestion
Hi @smals-chlo ,
can't the gcloud schema files be referenced as-is? I see their types are copied and split now across different yaml files.
This is an example of one our CBSS REST services where we use them: social-status-v2.zip
We use maven to find the gcloud schemas from Maven Central and unpack them.
To make reviewing easier, I've uploaded the Swagger schemas to a dedicated repo: https://github.com/belgif/rest-guide-example I'll put feedback in issues there, and stop reviewing it in this issue
there's a new version of the contracts in OpenAPI 3 which we'll go ahead with. There's a JAX-RS implementation of it not depending on internal Smals tooling. Implementation will be kept private (because we don't want to standardize on coding), but API published publicly.
Next steps:
- update the contracts in rest-guide-example repo
- review and improve contracts
- adapt implementation and publish it, review it
- update the REST guide to use examples from this API
work has resumed on the demo API. OpenAPI 3 schema updated on https://github.com/belgif/rest-guide-example
Next steps:
- finish implementation
- deploy demo API (which URL? e.g. https://rest-guide.gcloud.belgium.be/demo/v1 or https://rest-guide-demo.gcloud.belgium.be/employers/v1 )
- process any feedback (continuously)
- update the REST guide to use examples from this API
Implementation was changed to Spring Boot 3, but will be kept private (because we don't want to standardize on coding).
Implementation is finished, but demo API not published yet; infrastructure is being set up. I updated the OpenAPI files on https://github.com/belgif/rest-guide-example
Proposed URL: https://rest-guide.gcloud.belgium.be/demo/v1/
openapi file was updated in https://github.com/belgif/rest-guide-example following recent github issues; still working on publishing the demo API