[OpenNMS/opennms] ff7dab: NMS-20263: Tighten the ReST API documentation and ...
Marshall Massengill via opennms-cvs <[email protected]>
| Newsgroups | gmane.network.opennms.cvs |
|---|---|
| Message-ID | <OpenNMS/opennms/push/refs/heads/mm/NMS-20263-smoke/[email protected]> |
Branch: refs/heads/mm/NMS-20263-smoke
Home: https://github.com/OpenNMS/opennms
Commit: ff7daba6f5e9ba8cc5ffe0e99787b943a93c1975
https://github.com/OpenNMS/opennms/commit/ff7daba6f5e9ba8cc5ffe0e99787b943a93c1975
Author: Marshall Massengill <[email protected]>
Date: 2026-08-26 (Wed, 26 Aug 2026)
Changed paths:
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/MapFunctionDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/ReduceFunctionDTO.java
M features/bsm/rest/api/src/main/java/org/opennms/web/rest/v2/bsm/model/meta/FunctionMetaDTO.java
M features/bsm/rest/impl/src/main/java/org/opennms/web/rest/v2/bsm/BusinessServiceRestService.java
M features/geolocation/rest/src/main/java/org/opennms/web/rest/v2/GeolocationQueryDTO.java
M features/geolocation/rest/src/main/java/org/opennms/web/rest/v2/GeolocationRestService.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryRequest.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/QueryResponse.java
M features/measurements/api/src/main/java/org/opennms/netmgt/measurements/model/Source.java
M features/measurements/rest/src/main/java/org/opennms/web/rest/v1/MeasurementsRestService.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/BridgeElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/BridgeLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/BridgeLinkRemoteNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/CdpElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/CdpLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/EnlinkdDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/IsisElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/IsisLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/LldpElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/LldpLinkNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/OspfElementNodeDTO.java
M features/rest/model/src/main/java/org/opennms/web/rest/model/v2/OspfLinkNodeDTO.java
M features/status/rest/src/main/java/org/opennms/web/rest/v2/status/StatusRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AcknowledgmentRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AlarmRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AlarmStatsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AssetRecordResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AssetSuggestionsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/AvailabilityRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/CategoryRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ConfigRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/EventRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/FilesystemRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ForeignSourceConfigRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ForeignSourceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/GraphRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/GroupRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/HardwareInventoryResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/HeatMapRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/IfServicesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/InfoRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/KscRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/LogRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/MinionRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/MonitoringLocationsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/NodeRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/NotificationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OnmsIpInterfaceResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OnmsMonitoredServiceResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OnmsSnmpInterfaceResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/OutageRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/RequisitionRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ResourceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/ScheduledOutagesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/SnmpConfigRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/TimelineRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/UserRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/WebAssetsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/AgentConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/DataCollectionConfigResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/DatetimeformatConfig.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/EmailNorthbounderConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/JavamailConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/JmxDataCollectionConfigResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/SnmpTrapNorthbounderConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/SyslogNorthbounderConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/config/TrapdConfigurationResource.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/GroupUpdateForm.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v1/model/UserUpdateForm.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/AbstractDaoRestServiceWithDTO.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/AlarmRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/ApplicationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/DiscoveryRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/EventRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/IfServiceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/IpInterfaceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MenuRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MinionRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MonitoringLocationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/MonitoringSystemsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeCategoriesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeIpInterfacesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeMonitoredServiceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NodeSnmpInterfacesRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/NotificationRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/OutageRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/ProvisiondStatusRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/SituationsRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/SnmpInterfaceRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyAssetRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyViewDTO.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/TopologyViewRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/UserDefinedLinkRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/DataCollectionConfRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/EventConfRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/EventRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/NodeLinkRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/SnmpConfigRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/api/TrapdRestApi.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/infopanel/InfoPanelItem.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/infopanel/TopologyInfopanelRestService.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/AddEventConfSourceRequest.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/AlarmMemoRequest.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfEventEditRequest.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfEventPageResponse.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfSourceDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/EventConfUploadResponse.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/SnmpCollectionCreateSourceDto.java
M opennms-webapp-rest/src/main/java/org/opennms/web/rest/v2/model/Snmpv3UserDto.java
Log Message:
-----------
NMS-20263: Tighten the ReST API documentation and reconcile it with observed behaviour
Reviewer feedback was that the wording was too much and should state only what
is true. Every description now holds facts a reader can check against a running
instance. Advice, unmeasured performance claims, guesses at intent, appeals to
the reader and disclaimer-style negatives are gone, and the long tag overviews
are shorter. URL trees, parameter lists and enumerated values are untouched.
Rendered prose drops from 128969 to 118763 characters in v2 and from 156608 to
142234 in v1, roughly 24600 characters. Operation count, operationIds,
summaries, request and response schemas and every example are unchanged.
Four descriptions were wrong rather than merely wordy. All nine enlinkd DTO
pairs described both the create and the last-poll timestamp as a poll
timestamp. EventConfEventEditRequest said both members were optional while its
operation documents a 500 for a body carrying only `enabled`. The v1 event
publish description treated `uei` as required, contradicting the documented
empty-body 202. Nineteen literal newline escapes inside text blocks in the
heatmap descriptions rendered as a line break mid-sentence.
Seven places where a description and its response set disagreed are reconciled
against the instance rather than by deleting the prose. `GET /nodes/service-types`
answers 500 for an XML Accept, `PUT` and `DELETE /ipinterfaces/{id}` answer 400
for an ambiguous address, `POST /ksc` answers 415, `POST /events` does consume
`application/atom+xml`, and the three `/acks` reads answer 403 for a caller
holding none of the roles the filter chain requires, as the alarm reads already
documented. The status business-service list serializes as `businessservices`,
so the example that showed `business-services` was corrected; the sibling
`/business-services` list does emit the hyphenated key. Bridge elements are one
per discovered VLAN, with a single null-vlan entry when the device has no VLAN
table, not one per bridge base address.
To unsubscribe from these emails, change your notification settings at https://github.com/OpenNMS/opennms/settings/notifications
_______________________________________________
Please read the OpenNMS Mailing List FAQ:
http://www.opennms.org/wiki/index.php?page=MailingListFaq
opennms-cvs mailing list
To *unsubscribe* or change your subscription options, see the bottom of this page:
https://lists.sourceforge.net/lists/listinfo/opennms-cvs