Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Edit homepage news #45

Closed
wants to merge 8 commits into from
Closed

Edit homepage news #45

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3861b1c
Create homepage-news.md
benbosman Mar 28, 2018
1549eeb
Merge branch 'master' into atmire-Edit-homepage-news
benbosman Dec 21, 2018
3460deb
Create homepage-news.md
benbosman Mar 28, 2018
4712eac
Update homepage-news.md
benbosman Jan 7, 2019
e99f092
Update homepage-news.md
benbosman Jan 9, 2019
035bf06
Typing error
benbosman Feb 5, 2019
44a5afb
Merge remote-tracking branch 'atmire/Edit-homepage-news' into atmire-…
benbosman Feb 21, 2019
ec64623
Missing links to alternative languages
benbosman Feb 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 164 additions & 0 deletions homepage-news.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
# Homepage News Endpoints
[Back to the list of all defined endpoints](endpoints.md)

## Main Endpoint
**/api/config/pages**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the config category, what about web or cms? (btw maybe it is completely unnecessary to add a category see below)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cms is good for me as well


Provide access to the list of all static pages (currently home page news only). These are pages not specific to any items. The design of the REST contract should allow it to be extended to e.g. images as well.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know Lieven said it wasn't with high priority. But reading this text, it seems to be in an earlier stage.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The contract is actually not in an early phase.
The contract was designed to support the various pages without changes to the contract, but the Java implementation will be limited to the home page news for DSpace 7. This may be extended in DSpace 8, and the goal is to achieve this without changes to the contract

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, thank you for the clarification!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we already have a partial support for additional pages, see https://github.com/DSpace/DSpace/blob/dspace-6_x/dspace/config/spring/api/core-services.xml#L60
so we should provide a basic solution that still allow institutions to easily add new page with minimal effort.

Trying to design for the future without enough information about what and how we will go to implement is risky and can easily turn in over-engineering the current needs and provide something that we will found sub-optimal when really needed. If this will be the case we will be constrained by this premature design or we will end to broke the contract anyway.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This contract has been designed specifically to ensure institutions can easily add a page with minimal effort.
This is exactly the reason for the approach where static pages can be created/downloaded.
So contrary to the old JSPUI config you pointed at, the ability to create static pages won't require any changes in the backend.
All that's required is a POST of a new page with a different name.

Because the XMLUI supports home page news per language, multiple pages can be created here.

Example:
```json
{
"_embedded": {
"pages": [
{
"uuid": "004a297e-fd06-4662-ae51-73e4b7c165c8",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how will we get that? where we will store the mapping between the uuid and the name that is what currently identify the page?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The storage of the static pages will happen in the database (uuid, name, title, language, bitstream)

"name": "home-page-news",
"title": "DSpace Demo Repository",
"sizeBytes": 234,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not really the size of the page but just the size of the fragment. Also in future when we will be able to deliver user defined content as an additional page we will probably include his content inside the default theme of DSpace making impossible to estimate the page size in advance and mostly useless the information about the size of the fragment... it could become useful when the "page" is a css, js or other media

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is indeed the size of the fragment, and the user will download that fragment.
Angular will integrate the fragment in the theme

For HTML the fragment is indeed often small, but storing the size does ensure it's immediately useful for other media, and no additional effort

"language": "en",
"type": "page",
"_links": {
"content": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/004a297e-fd06-4662-ae51-73e4b7c165c8/content"
},
"format": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/004a297e-fd06-4662-ae51-73e4b7c165c8/format"
},
"languages": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/004a297e-fd06-4662-ae51-73e4b7c165c8/languages"
},
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/004a297e-fd06-4662-ae51-73e4b7c165c8"
}
},
"_embedded": {
"format": {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems to suggest the use of bitstream in future to store our pages/page fragments/media.
I like this idea but again if we are not going to do that now, I suggest to just model what we have now.

"id": 22,
"shortDescription": "XHTML",
"description": "XHTML",
"mimetype": "text/html; charset=utf-8",
"supportLevel": 0,
"internal": false,
"extensions": null,
"type": "bitstreamformat",
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/core/bitstreamformats/22"
}
}
}
}
},
]
}
}
```

## Single page
### View page
**/api/config/pages/<:uuid>**

Provide detailed information about a static page. The JSON response document is as follow
```json
{
"uuid": "004a297e-fd06-4662-ae51-73e4b7c165c8",
"name": "home-page-news",
"title": "DSpace Demo Repository",
"sizeBytes": 234,
"language": "en",
"type": "page"
}
```

Exposed links:
* format: link to the format resource associated with the file (XHTML, jpeg, etc.). TODO: verify how images can be supported
* content: link to access the actual content of the page
* languages: link to language alternatives of this page

### Edit page: Multipart POST Method
**POST /api/config/pages**

A multipart POST request will result in creating a new file identified by the name.

Send detailed information about a static page, and the actual file. The sizeBytes and uuid is not required, but the other attributes are applicable

**PUT /api/config/pages/<:uuid>**

A multipart PUT request will result in an update of the file identified by the uuid.

Send detailed information about a static page, and the actual file. The sizeBytes is not required, but the other attributes are applicable

### Delete page
**DELETE /api/config/pages/<:uuid>**

A DELETE request will typically result in deleting the file identified by the uuid. If the file didn't exist yet, the delete will fail

## Linked entities
### Format
**/api/config/pages/<:uuid>/format**

Example: Similar to bitstreams

It returns the format of the resource

### Content
**/api/config/pages/<:uuid>/content**

Example: Similar to bitstreams

It returns the actual content (bits) of the resource

Response Headers:

* **Content-Type**: the mimetype as recorded for the file
* **Content-Length**: the size in bytes of the content

The supported **Request Headers** are:
* If-Modified-Since:
* If-None-Match:

### Languages
**/api/config/pages/<:page-name>/languages**

Example:
```json
{
"_embedded": {
"languages": [
{
"lang": "en",
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/004a297e-fd06-4662-ae51-73e4b7c165c8"
}
}
},
{
"lang": "es",
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/e942550b-0362-4b11-920b-44a6e80a69f9"
}
}
},
{
"lang": "fr",
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/6fdd5b9f-ffc7-4896-8d01-5ff33aba589f"
}
}
}
],
"_links": {
"self": {
"href": "https://dspace7.4science.it/dspace-spring-rest/api/config/pages/004a297e-fd06-4662-ae51-73e4b7c165c8/languages"
}
}
}
}
```

It returns all the language variants of the resource